Amazon SES

Send every Matomo email through the Amazon SES API v2 over HTTPS. You don't need SMTP credentials or an open port 25/587.

The plugin replaces the Matomo mail transport. Scheduled reports (including PDF attachments), password resets, invitations, alerts and all other emails go through Amazon SES without any other change to Matomo.

Features

• Amazon SES API v2 (SendEmail with raw MIME), signed with AWS Signature V4. No AWS SDK is bundled, so the plugin stays small.
• Credentials are resolved in this order: the plugin settings, the AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY environment variables, the ECS task role, then the EC2 instance profile (IMDSv2).
• Optional sender override, for an address or domain verified in SES.
• Optional configuration set, so you can publish bounces, complaints and deliveries to SNS, CloudWatch or EventBridge.
• An admin page (Administration → System → Amazon SES) with the effective configuration (region, credentials source, sender) and a Send test email button. It makes no AWS call besides sending, so an IAM policy that only allows sending is enough.
• Every setting can also be set in config.ini.php for container and infrastructure-as-code deployments.
• Errors are never hidden. If SES rejects a message, Matomo logs the exact AWS error; there is no silent fallback to SMTP.

Requirements: Matomo 5, PHP 7.2.5+ with the cURL extension, and an Amazon SES identity (email address or domain) verified in the region you use.

• Amazon SES status and test email

  

• Settings

  

See the README for installation, configuration (UI, config.ini.php, environment variables), the required IAM policy and the development environment.

Which emails are sent through Amazon SES?

All of them. The plugin replaces the Matomo mail transport, so scheduled reports, alerts, password resets, invitations and emails sent by other plugins all go through SES while the plugin is activated.

What happens if an SMTP server is also configured?

Amazon SES always wins while the plugin is active: Matomo uses a single mail transport, and the plugin replaces the core SMTP / mail() transport. The host, port, username, password and encryption set under General settings → Email server settings are ignored, and no email is sent twice. The Amazon SES admin page shows a warning when an SMTP server is configured.

The sender address and name from that same form are still used: they are Matomo's noreply address and name, and the plugin uses them unless you set Sender email / Sender name in the plugin settings.

If Amazon SES fails, the plugin does not fall back to SMTP. Deactivate the plugin to go back to SMTP; no other change is needed.

I get "Email address is not verified".

Amazon SES only sends from verified identities. Verify the sender address, or better its whole domain, in the SES console of the same region configured in the plugin. Then either use that address as Matomo's noreply address or set it as Sender email in the plugin settings.

In sandbox mode the recipients must be verified too, and if your IAM policy restricts Resource to specific identities, the recipients must be listed there as well. Request production access in the SES console to email any user.

Where do the credentials come from?

The plugin tries, in this order:

1. The access key set in the plugin settings (or in config.ini.php).
2. The environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (plus AWS_SESSION_TOKEN).
3. The ECS / Fargate task role.
4. The EC2 instance profile, via IMDSv2.

The status page shows which source is in use.

What happens if Amazon SES is down or rejects a message?

The send fails and Matomo logs the AWS error message (for example MessageRejected or Throttling). The plugin never falls back to SMTP silently, so a configuration problem doesn't go unnoticed.

How do I handle bounces and complaints?

Create an SES configuration set with an event destination (SNS, CloudWatch, EventBridge…) and enter its name in the plugin settings. By default SES also adds bouncing addresses to your account-level suppression list.

Can I use a VPC endpoint or a local SES mock?

Yes. Set endpoint in the [AmazonSES] section of config.ini.php, or set the AWS_ENDPOINT_URL_SESV2 environment variable. The endpoint must use https://. A local mock that only speaks plain http:// also needs allowInsecureEndpoint = 1 (or AMAZONSES_ALLOW_INSECURE_ENDPOINT=1): never enable it for a remote host, as AWS credentials and email contents would travel unencrypted.

Does it work behind an HTTP proxy?

Yes. Calls to the SES API use the proxy configured in Matomo's [proxy] section. Calls to the ECS/EC2 metadata endpoints never go through the proxy.

Is there a size limit?

Amazon SES v2 accepts messages up to 40 MB, including attachments after encoding.