Migrate to Mailtrap from Amazon SES

Migration Checklist

1. Authenticate your domain
   Add and verify your domain before sending. Follow the Domain Setup article at docs.mailtrap.io.

2. Get your API token
   Mailtrap auto-generates a token when you add a domain. Find it under Settings → API Tokens. Read more on API tokens.
3. Update your integration
   Swap your Amazon SES endpoint and credentials for Mailtrap’s (API or SMTP). See the migration sections below.
4. Migrate templates
   Both platforms use Handlebars, so content migrates directly. See the templates sections below. 
5. Migrate suppressions
   Export SES suppressions and import them into Mailtrap via CSV or manually. Click here for more information.
6. Migrate users
   Add users from the User Management tab and review permissions during migration.
7. Set up webhooks
   Follow the Mailtrap Webhooks step-by-step guide.
8. Security and compliance
   Visit the Trust Center page to review Mailtrap’s security practices and compliance standards.

Concepts

Before going over the technical details, it’s important to clear up some key concepts.

Sending domains

SES equivalent: Verified Identities (Easy DKIM / BYODKIM)

Both platforms require DNS-based domain authentication with SPF, DKIM, and DMARC. SES calls these “verified identities” and supports:

• Easy DKIM (AWS generates keys, you add three CNAME records) or 
• BYODKIM (you supply your own signing keys). 
• Custom MAIL FROM domain for SPF alignment.

Mailtrap’s domain setup uses the same DNS standards – SPF, DKIM, DMARC. DKIM records can be added alongside SES’s (different selectors, no conflict), and one DMARC record covers both. For SPF, however, you must merge Mailtrap’s include into your existing SPF record rather than adding a separate one.

Separate sending streams

SES equivalent: N/A – single service, single endpoint per region

SES routes all email through one regional endpoint. You can use Configuration Sets to separate tracking and event routing, but the underlying infrastructure is shared.

Mailtrap separates transactional and bulk email into distinct infrastructure:

• Transactional Stream – For sending user-triggered emails like welcome emails and password resets.
• Bulk Stream – For sending promotional, marketing emails like newsletters and product updates.

By keeping the sending infrastructures separate, you are able to:

• Protect your transactional email reputation from the performance of your bulk campaigns
• Ensure each stream routes through the right IP pools
• Give mailbox providers the signals they need to categorize and deliver your emails correctly

Email categories

SES equivalent: Configuration Sets + Message Tags (EmailTags)

SES uses two mechanisms for categorizing email. Configuration Sets define where event data goes (CloudWatch, Kinesis Firehose, SNS) and apply sending rules. 

• Message Tags (EmailTags) are name-value pairs attached to individual sends for filtering events and metrics.
• Mailtrap uses Email Categories — set via the category field in the API or the X-MT-Category header in SMTP.

Key difference: SES’s tagging system is more granular (multiple key-value pairs per message, tied into AWS’s observability stack). Mailtrap assigns one category string per message, which keeps things simpler for most use cases.

Organization & sub-accounts

SES equivalent: IAM Users, Roles, Policies + Sending Authorization

SES inherits AWS’s IAM model for access control – fine-grained policies, cross-account sending authorization, and role-based access. This is powerful but adds operational complexity, especially for teams that only need email.

Mailtrap offers Organization and sub-account management, which lets you manage complex setups involving multiple teams, clients, environments, or products under a single Organization. To start using the feature, you first need to enable it under the Organization tab.

Note: The feature is available to from Business plan onward.

Terminology comparison

API migration

Authentication

SES and Mailtrap use fundamentally different auth models:

SES auth is tightly coupled to AWS IAM. When migrating, you replace the SigV4 signing logic (or AWS SDK calls) with a single Bearer token header. This significantly simplifies your sending code.

API mapping

Outbound Sending API JSON Field Mapping

Code snippets

Note: SES nests content deeply (Content.Simple.Body.Html.Data), requires regional endpoints, and uses AWS SigV4 auth. Mailtrap uses a flat payload structure with a Bearer token – fewer lines of code, no SDK dependency for signing.

SMTP migration

Migration notes:

• Host: Replace email-smtp.{region}.amazonaws.com with the appropriate Mailtrap host. If you send both transactional and bulk email over SMTP, you now need two separate SMTP configurations.
• Username: SES uses your IAM Access Key ID. Mailtrap requires the literal string api.
• Password: This is the biggest gotcha. SES SMTP passwords are not your IAM Secret Access Key – they’re derived from it via a signing algorithm. Mailtrap just uses the API token directly. No derivation step needed.
• Regional vs global: SES SMTP is regional (credentials are region-specific). Mailtrap SMTP is global.
• Ports 2587/2465: SES offers additional high-numbered ports. Mailtrap uses 587 (recommended), 25, and 2525.

For more information on migrating your SMTP configuration, click this link. ⬅️

Rate limits & quotas

Key differences:

• SES counts recipients, not messages, against your quota. One email to 10 recipients counts as 10.
• SES quotas are per-region. You can send from multiple regions to multiply your effective quota, but each requires separate configuration.
• SES starts in sandbox mode (200 emails/day, 1/sec) — you must request production access. Mailtrap’s free plan starts at 1,000 emails/month with no sandbox restrictions.
• SES has more several non-sending API calls (IAM roles, Lambda functions, etc.) and they follow the same rate as expressed above.

Email templates

Both platforms use Handlebars. If your SES templates use {{variable}} syntax, the markup migrates directly.

Syntax comparison

Migration notes: SES requires TemplateData as an escaped JSON string ("{"name": "John"}"). Mailtrap accepts template_variables as a regular JSON object ({"name": "John"}). This simplifies your code – no double-encoding.