Download the PHP package etailors/mautic-amazon-ses without Composer

Mautic AWS SES Plugin with SNS Callback

This plugin provides integration between Mautic 5, 6 and 7 and Amazon SES for sending emails through AWS. It also integrates with Amazon SNS for handling email feedback such as bounces and complaints via callbacks. (PHP >= 8.1 required; Note: Mautic 7 itself requires PHP 8.2)

This is a custom plugin inspired by the structure of:

• mabumusa1/ses-plugin
• ts-navghane/sparkpost-plugin

Feel free to suggest improvements or provide feedback — this is my first Mautic plugin and community contributions are welcome.

Features

• Send emails through Amazon SES using the API.
• Support for setting AWS regions and optional custom rate limits in the DSN.
• Integration with Amazon SNS to process bounces and complaints via callback.
• Built-in rate limiting to honor SES sending quotas.
• Dynamic batch size matching the current SES max send rate.
• Auto-fetch and cache your SES sending quota.
• Manual override of rate limit with ratelimit DSN option.
• Optional retry handling for partial email failures.

Installation

1. Download and Install the Plugin

Install manual

1. Download or clone the repository to your Mautic plugins directory:

2. Clear Mautic’s cache:

3. Go to Mautic Settings > Plugins and click the “Install/Update Plugins” button.

Install via Composer

If you prefer installing via Composer, run the following command from your Mautic root directory:

Version number

Then clear the cache and reload the plugins:

Note:
The plugin will automatically install into plugins/AmazonSesBundle.

2. Configure Amazon SES Settings

1. In Mautic, navigate to Settings > Email Settings.
2. Select the newly installed AWS SES option.

3. In the DSN field, enter your connection string in the following format:

   • Replace <AWS_ACCESS_KEY> and <AWS_SECRET_KEY> with your AWS credentials.
   • Replace <AWS_REGION> with your AWS region (e.g., us-east-1).
   • Optionally set ratelimit to override the SES max send rate manually.
   • Set sns_topic_arn to the exact SNS topic ARN used for feedback. The callback fails closed when no allowed topic is configured. For multiple topics, set amazon_ses_sns_topic_arns as an array in Mautic's local configuration.
4. Set the region in the options parameter, for example:

3. AWS SES Configuration

1. Ensure that you have verified your domain and email addresses in AWS SES.

2. Set up the appropriate IAM user with permissions to send emails via SES.
   Please make sure you create a new IAM user directly via IAM instead of upgrading an SMTP user with the permission: sending via SES API.

   There are known issues when upgrading SMTP-only users — see: issue #28.

Your IAM user must have permission to send and get account limits. Here’s an example policy:

4. Available Regions

SNS Callback Configuration

To receive feedback from Amazon SES regarding bounces and complaints, you need to set up Amazon SNS.

1. Go to your Amazon SNS Dashboard.
2. Create a new Topic (or use an existing one) for SES feedback.

3. Subscribe to this topic with an HTTPS endpoint using the following URL:

4. Ensure your topic sends notifications for bounces, complaints, and delivery status.
5. Ensure the exact topic ARN is configured as sns_topic_arn in the mailer DSN. The plugin verifies the AWS signature and topic before processing any callback.
6. For classic identity-based SNS notifications, enable Include original headers for bounce and complaint notifications on the verified SES identity. Mautic uses the X-EMAIL-ID header to attribute feedback to the email statistics. Configuration-set event publishing can use the X-EMAIL-ID message tag added by this plugin instead.
7. Test your callback configuration by sending test emails and reviewing Mautic logs to verify feedback is processed correctly.

Batch Limit & Throttling

To avoid exceeding SES rate limits, this plugin automatically:

• Caches the current maxSendRate returned by AWS SES.
• Dynamically adjusts the batch size to match that rate.
• Throttles outgoing email API calls using usleep().
• Allows overriding the send rate via ratelimit DSN option.

This prevents common errors like TooManyRequests while maximizing throughput.

Debugging

• To troubleshoot email sending or SNS callback issues, check Mautic’s logs:

• You can also monitor SES and SNS performance in Amazon CloudWatch.

Contributions & Feedback

This is my first Mautic plugin, so I’m open to any feedback or improvements.
Feel free to open an issue or submit a pull request if you find a bug or have a feature request!

License

This project is licensed under the MIT License — see the LICENSE file for details.

Changelog

See CHANGELOG.md for release notes. Version 1.0.31 maintains compatibility with PHP 8.1 for Mautic 6 users, while supporting Mautic 7 (which requires PHP 8.2).