Why Matomo email stops reaching inboxes

Matomo depends on outbound mail for several features that administrators rarely test until something breaks: scheduled PDF and HTML reports, custom alerts triggered by traffic thresholds, two-factor recovery messages, password resets, and invitation emails for new users. On a fresh install Matomo defaults to the PHP mail() function, which hands the message directly to the server's local mail transport. On a Managed Cloud shared platform running LiteSpeed and CloudLinux, that path works for messages sent to local accounts but frequently fails for external recipients because the message carries no authentication, an invalid envelope sender, or a From header that does not match any domain hosted on your account.

The symptom is almost always silent. Matomo queues the report, the cron job runs, the task is marked complete in the interface, and nothing arrives. Receiving providers such as Gmail, Outlook, and Yahoo evaluate the sending IP's reputation together with SPF, DKIM, and DMARC alignment. When Matomo sends through raw mail() with a header like From: noreply@localhost or an address on a domain you do not control, the message is either rejected at the SMTP conversation or dropped into spam with no bounce returned to the application. Because you operate as an unprivileged hosting user, you cannot inspect the server-wide mail queue or read the Exim/MTA logs, so the failure leaves almost no trace inside your account.

The reliable fix is to stop relying on the implicit mail() path and instead point Matomo at an authenticated SMTP account that you create inside cPanel or DirectAdmin. Authenticated SMTP means every message is tied to a real mailbox on a domain you host, which lets the server stamp the outgoing mail with the correct identity and lets receiving servers verify it against your DNS. This single change resolves the majority of delivery problems before you touch anything else.

Creating a mailbox and configuring SMTP in Matomo

Begin by creating a dedicated email account for Matomo so that delivery problems never get tangled with a human mailbox. In cPanel Jupiter open Email Accounts, click Create, and make an address such as matomo@yourdomain.com with a strong password. In DirectAdmin Evolution the equivalent is E-Mail Manager → E-Mail Accounts → Create Account. After creating the mailbox, open its Connect Devices (cPanel) or mail client configuration screen to confirm the exact outgoing hostname. On most Hostiso accounts the authenticated SMTP host is mail.yourdomain.com on port 465 with SSL/TLS, or port 587 with STARTTLS. Use the full email address as the username.

Matomo stores its mail configuration in the General Settings area and writes it to config/config.ini.php. Navigate to Administration (the gear icon) → System → General Settings, then expand the Email server settings panel. Set the transport to SMTP and fill in the fields:

  • SMTP server address: mail.yourdomain.com
  • Encryption: ssl for port 465, or tls for port 587
  • SMTP port: 465 or 587
  • Authentication type: Login
  • SMTP username: matomo@yourdomain.com
  • SMTP password: the mailbox password you created

Save the settings. Matomo exposes a send a test email link directly under the panel; use it and send to an external address you can check, not to another mailbox on the same account. If you prefer to edit the file directly through the cPanel or DirectAdmin File Manager, the relevant block in config/config.ini.php looks like this:

[mail]
transport = "smtp"
port = 465
host = "mail.yourdomain.com"
type = "Login"
username = "matomo@yourdomain.com"
password = "your-mailbox-password"
encryption = "ssl"

Edit this file carefully: keep the exact section header and quoting, and never change line endings to a format that corrupts the INI structure, or Matomo will fall back to defaults. After saving, reload the General Settings page to confirm the values persisted.

Sender address, SPF, and DKIM alignment

Authenticated SMTP solves the connection, but the From address and your DNS records decide whether the inbox accepts the message. The most common remaining mistake is a mismatch between the address Matomo sends from and the authenticated mailbox. Keep both on the same hosted domain. In Matomo the report sender is not the SMTP username by default, so check Personal → Settings and the individual report configuration under Email Reports to confirm the sending identity resolves to an address on yourdomain.com. A sender on a domain you do not host will fail SPF checks regardless of how clean your SMTP authentication is.

Because mail now leaves through your own domain's mail service, the server already includes it in the domain's SPF record when the zone was provisioned. Verify this in cPanel under Email Deliverability, which shows the status of SPF and DKIM for each domain and flags any problems with a repair action. DirectAdmin exposes the same checks under E-Mail Manager → SPF & DKIM. A valid SPF record for a Hostiso-hosted domain typically ends with the server's include mechanism and a ~all or -all qualifier; do not hand-edit it unless the deliverability panel reports a missing entry, and if it does, use the panel's own Install the suggested record button rather than editing zone files you cannot access directly.

DKIM signs outgoing mail with a private key so receivers can confirm the message was not altered and genuinely came from your domain. The Email Deliverability tool generates the DKIM key pair and publishes the public selector record automatically when your DNS is managed on the same platform. If your domain uses external nameservers, the panel displays the exact TXT records you must copy into your DNS provider's dashboard. Once SPF and DKIM both show a green status, send another Matomo test report and inspect the received message headers for spf=pass and dkim=pass. Those two results are the difference between the inbox and the spam folder for recurring automated reports.

Scheduled report delivery, cron, and diagnostics

Matomo does not run a persistent mail queue; scheduled reports are generated and sent when the archiving cron task executes. If your reports never fire while manual test emails succeed, the problem is the scheduler rather than SMTP. Confirm that the Matomo cron entry exists under cPanel Cron Jobs or DirectAdmin Cron Jobs, calling the console with the PHP binary from the correct version. A typical entry runs every hour:

/usr/local/bin/php /home/youruser/public_html/matomo/console core:archive --url=https://yourdomain.com/matomo/ >/dev/null 2>&1

Use the PHP Selector to confirm which PHP version Matomo runs under, then match the interpreter path; calling the wrong binary silently skips the task. Memory and execution limits for the console run come from your .user.ini in the Matomo document root, where values such as memory_limit = 256M and max_execution_time = 300 keep larger report generations from being killed mid-send.

When delivery still fails, the application's own log is your best unprivileged window. Enable debug logging temporarily in config/config.ini.php with a [log] section setting log_writers[] = "file" and log_level = "INFO", then reproduce the test send and read tmp/logs/matomo.log through File Manager. SMTP authentication rejections, TLS handshake failures, and relay-denied errors appear there verbatim. Also check the PHP error_log in the Matomo directory for connection timeouts, which usually indicate the wrong port or an encryption mismatch between port 465 and the tls setting. If you also run other PHP applications that share these delivery concerns, the same authenticated-SMTP principle applies, and our write-up on Mautic database maintenance covers related background-job behavior on the same platform. Once the log shows a clean handshake and the received headers pass SPF and DKIM, raise the log level back to a quieter setting so the file does not grow unchecked.