Migrate to Mailtrap from SendGrid

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 SendGrid 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. See the templates sections below.
5. Migrate suppressions
   Export SendGrid 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

SendGrid equivalent: Domain Authentication

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 SendGrid relies on. 

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

Separate sending streams

SendGrid 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

SendGrid equivalent: Categories

Like SendGrid, 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 if you are using SMTP or pass the category name in the category field if you are sending via API.
• Using Categories with SendGrid: Pass categories inside the X-SMTPAPI JSON header if you are using SMTP, or pass an array of strings in the categories field if you are sending via API. SendGrid supports up to 10 categories per email.

Organization & sub-accounts

SendGrid equivalent: Subusers

Mailtrap offers its Organization & sub-accounts feature, 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

Both platforms use Bearer token authentication in the Authorization header – same pattern, different key.

No code change needed beyond swapping the key value. The header format is identical.

API mapping

Outbound Sending API JSON Field Mapping

SendGrid uses POST https://api.sendgrid.com/v3/mail/send; Mailtrap uses POST https://send.api.mailtrap.io/api/send. Both accept application/json.

Code snippets

Note:

• Flat structure vs. personalizations wrapper. SendGrid nests recipients, subjects, and dynamic data inside a personalizations array. Mailtrap keeps things flat: to, cc, bcc, subject, and template_variables all live at the root of the request body. For single-email transactional calls (the common case), this cuts the nesting and the boilerplate.
• Body fields: content[] array vs. html/text. SendGrid wraps body content in a content array where each element declares a MIME type and a value. Mailtrap uses dedicated html and text fields at the root. Less indirection, easier to read in a diff.
• Auth: identical pattern. Both use Authorization: Bearer <api_key>. Swap the key, update the endpoint URL, adjust the payload structure.
• Sending stream selection is structural. SendGrid routes all email through a single endpoint (/v3/mail/send). Mailtrap uses separate endpoints – send.api.mailtrap.io for transactional, bulk.api.mailtrap.io for bulk – isolating the two at the infrastructure level.

SMTP migration

Migration notes:

• Mailtrap uses separate SMTP hosts for transactional (live.smtp.mailtrap.io) and bulk (bulk.smtp.mailtrap.io) streams. SendGrid uses a single host (smtp.sendgrid.net) for all sending.
• The SMTP username is a literal string in both cases, but they differ: Mailtrap uses api, SendGrid uses apikey. Note that neither is a placeholder and both must be entered exactly as shown.

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

Rate limits & quotas

Email templates

Both SendGrid and Mailtrap use Handlebars syntax for dynamic templates. Basic variable insertion ({{variable}}), conditionals ({{#if}}), iteration ({{#each}}), and unescaped HTML ({{{variable}}}) work the same way on both platforms. Your template markup will mostly port directly; the differences are in helper functions, default value syntax, and how variables are passed via the API.

Syntax comparison

Migration notes

• Variables and loops transfer directly. Both platforms use standard Handlebars – {{var}}, {{#if}}, {{#each}}, and {{{unescaped}}} work identically. No template markup changes needed for these.
• Default values need rewriting. SendGrid’s insert helper ({{insert name "default=Customer"}}) is a SendGrid-specific extension. In Mailtrap, use a standard Handlebars {{#if}} / {{else}} block instead: {{#if name}}{{name}}{{else}}Customer{{/if}}. More verbose, but standard Handlebars – no vendor lock-in.
• Date formatting moves to your application layer. SendGrid’s {{formatDate timestamp "MM/DD/YYYY"}} helper formats dates inside the template. Mailtrap doesn’t support a date formatting helper, so format dates in your code before passing them as template variables. If you have templates with formatDate calls, replace each with a pre-formatted string variable (e.g., {{formatted_date}}) and compute the value server-side.
• Comparison and logical helpers aren’t available. SendGrid supports greaterThan, lessThan, notEquals, and, or, and length helpers for in-template logic. Mailtrap uses standard Handlebars, which doesn’t include these. Move that logic to your application: compute the result and pass a boolean or pre-resolved value as a template variable.
• Variable passing is almost identical. Both use a JSON object – rename the field from dynamic_template_data (nested inside personalizations[]) to template_variables (at the root level). The variable structure itself stays the same.
• Template IDs change format. SendGrid dynamic templates use a d- prefixed string (e.g., d-abc123def456). Mailtrap uses template_uuid. You’ll need to recreate templates in Mailtrap and update the IDs in your code.
• Templates override subject and content. In SendGrid, a dynamic template with a subject line overrides any subject set in the API request. Mailtrap behaves the same way – if the template includes a subject, the subject field in the API request is ignored.