Migrate to Mailtrap from Postmark

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 Postmark endpoints and credentials for Mailtrap’s (API or SMTP). See the migration sections below.
4. Migrate templates
   Note that Postmark uses Mustachio and Mailtrap uses Handlebars. See the templates sections below.
5. Migrate suppressions
   Export Postmark 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

Postmark equivalent: Domains + Sender Signatures

Postmark manages sender identity under Sender Signatures, which supports two options: 

1. Individual email address verification (Sender Signature)
2. Full domain verification (Domain)

For production sending, domain verification is recommended – it requires adding DKIM DNS records, and optionally a Return-Path CNAME record for SPF/DMARC alignment and bounce tracking.

Mailtrap’s domain setup uses the same DNS standards – SPF, DKIM, DMARC. DKIM records can be added alongside Postmark’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.

See the Mailtrap domain setup guide for step-by-step instructions.

Separate sending streams

Postmark equivalent: Message Streams (Transactional + Broadcast)

This is one area where Postmark and Mailtrap are closely aligned. Postmark separates transactional and broadcast email via Message Streams, with distinct SMTP hosts:

• Postmark: 
  • smtp.postmarkapp.com (transactional) 
  • smtp-broadcasts.postmarkapp.com (broadcast)
• Mailtrap:
  • live.smtp.mailtrap.io (transactional)
  • bulk.smtp.mailtrap.io (bulk)

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

Postmark equivalent: Tags (single string per message, max 1,000 characters)

Both platforms use a single tag/category per message for grouping and analytics. Postmark uses the Tag field in the API and X-PM-Tag header in SMTP. Mailtrap Email Categories use the category field in the API and X-MT-Category header in SMTP.

Nearly identical approach; just rename the field/header.

Organization & sub-accounts

Postmark equivalent: Users and Permissions (Account Owner, Admin, Technical, Billing roles)

Postmark manages access through a Team system with four role types under Account settings. Mailtrap offers Organization and sub-account management from Business plan onwards. 

Terminology comparison

API migration

Authentication

Both platforms use a token in a request header, but with different header names:

Simple header rename; the auth model is conceptually the same.

API mapping

Outbound Sending API JSON Field Mapping

Code snippets

Note: Postmark uses PascalCase field names (HtmlBody, TextBody) and comma-separated recipient strings. Mailtrap uses snake_case/lowercase fields and recipient arrays with separate email/name properties. Both use flat JSON – no deep nesting.

SMTP migration

Migration notes:

• Host swap: Both platforms separate transactional and bulk/broadcast into distinct SMTP hosts. Replace smtp.postmarkapp.com → live.smtp.mailtrap.io and smtp-broadcasts.postmarkapp.com → bulk.smtp.mailtrap.io.
• Username: Postmark uses the Server API Token as both username and password. Mailtrap uses the literal string api as username and the API token as password.
• Ports: Same on both sides – 587, 25, 2525. No port changes needed.
• SMTP headers: Replace X-PM-Tag → X-MT-Category, X-PM-Metadata-* → X-MT-Custom-Variables, and X-PM-Message-Stream → use the appropriate Mailtrap SMTP host instead.

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

Rate limits & quotas

Email templates

Postmark uses Mustachio (a Mustache-inspired engine). Mailtrap uses Handlebars. The syntax is similar but not identical – you’ll need to review templates during migration.

Syntax comparison

Migration notes:

• Variables and loops transfer directly – same {{var}} and {{#each}} syntax.
• Conditionals need attention: Postmark uses {{#var}}...{{/var}} for truthy checks. Mailtrap Handlebars uses {{#if var}}...{{/if}}. Similarly, Postmark’s {{^var}}...{{/var}} becomes {{else}} blocks in Handlebars.
• Variable passing is almost identical – both use a JSON object. Just rename the field from TemplateModel to template_variables.
• Inline CSS: If you rely on Postmark’s InlineCss flag, you’ll need to inline CSS in your HTML before sending through Mailtrap, or use a build-step tool like juice to handle it.