Migrate to Mailtrap from Mailgun

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 Mailgun endpoints and credentials for Mailtrap’s (API or SMTP). See the migration sections below.
4. Migrate templates
   Both platforms use Handlebars, so content migrates directly. Update t:variables → template_variables and string names → template_uuid.
5. Migrate suppressions
   Export Mailgun 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. Mailgun’s 5 role types don’t map 1:1 to Mailtrap roles, so 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

Mailgun equivalent: Domain Verification (with Automatic Sender Security for managed DKIM)

Before being able to send emails with Mailtrap, you first need to add and verify your sending domain. For domain verification, Mailtrap provides DNS records, which are the same standards Mailgun relies on. 

DKIM records can be added alongside Mailgun’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.

To learn how to verify your domain, you can read our step-by-step Knowledge base article, or watch the video we prepared for you. The whole process takes ~15 minutes.

Note: Even if your domain is already authenticated in Mailgun, you’ll need to add it to Mailtrap separately. Existing DNS records may need to be replaced or consolidated; you can’t use them as-is.  

Separate sending streams

Mailgun equivalent: N/A

Mailtrap provides two separate email infrastructures, or sending streams:

• 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

Mailgun equivalent: Tags (o:tag parameter)

Like Mailgun’s Tags, Mailtrap offers an Email Categories feature that lets you track the performance of different types of emails (e.g., welcome emails, password resets, etc.).

• Using Email Categories with Mailtrap: Insert a category name into the X-MT-Category header (SMTP) or pass the category name in the category field (API).
• Using Tags with Mailgun: Pass tags via the o:tag form parameter (API), or use the X-Mailgun-Tag header (SMTP). Mailgun supports multiple tags per message.

Organization & sub-accounts

Mailgun equivalent: Subaccounts + Multi-User Access with Roles

Mailtrap offers its Organization & Sub-accounts feature from Business plan onwards. It 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.

Notes: 

• Mailgun provides Subaccounts (Enterprise-only) for fully isolated child environments with separate domains, IP pools, and API keys. Multi-user access uses Role-Based Access Control with 4 role types – Admin, Developer, Analyst, and Support – also available on Enterprise and select Business plans.
• With Mailtrap the feature is available to from Business plan onward.

Terminology comparison

*Mailgun’s Events API has been deprecated. 
**Mailgun’s old Tags API has been deprecated.

API migration

Authentication

Both Mailtrap and Mailgun authenticate API requests using an API key passed in the Authorization header. The key difference is the method:

When migrating, change your authentication from Basic Auth to Bearer token format.

Note: Mailtrap automatically creates a token when you add a domain. By default, the token has Domain Admin access permission. Add or remove token permissions in the API Tokens menu under Settings.

API mapping

Outbound Sending API JSON Field Mapping

Mailgun: POST /v3/{domain}/messages with multipart/form-data

Mailtrap: POST /api/send with application/json

Code snippets

Note:

• Content type: Mailtrap accepts application/json; Mailgun uses multipart/form-data.
• Auth method: Mailtrap uses Bearer token; Mailgun uses Basic Auth (–user).
• Domain in URL: Mailgun requires the sending domain in the API path (/v3/{domain}/messages); Mailtrap does not.
• Regional endpoints: Mailgun has separate API hosts for US and EU. Mailtrap uses a single global endpoint.

SMTP migration

Migration notes:

• Mailtrap uses separate SMTP hosts for transactional (live.smtp.mailtrap.io) and bulk (bulk.smtp.mailtrap.io) streams. Mailgun uses a single host (smtp.mailgun.org) for all sending.
• The SMTP username differs: Mailtrap uses the literal string api, while Mailgun uses a full email address credential (e.g., postmaster@yourdomain.com).
• Mailgun’s SMTP credentials are managed per-domain and are separate from API keys. Mailtrap uses the same API token for both API and SMTP authentication.

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

Rate limits & quotas

Email templates

Both Mailtrap and Mailgun use Handlebars syntax, so variable insertion ({{variable}}), conditionals, loops, and nested objects work identically and require no changes when migrating.

The differences only appear in a few specific cases:

Syntax comparison

Migration notes: Mailgun has a separate variable system for batch sending that uses %recipient.varname% syntax (percent-delimited), distinct from its Handlebars template engine. When migrating batch sends, convert these to Mailtrap’s approach.