Migrate to Mailtrap from Brevo

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 Brevo endpoints and credentials for Mailtrap’s (API or SMTP). See the migration sections below.
4. Migrate templates
   Brevo and Mailtrap don’t use the same templating language, so you can’t migrate templates directly. See the templates sections below.
5. Migrate suppressions
   Export Brevo 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

Brevo equivalent: Authenticate your domain (Brevo code + DKIM + DMARC)

Both platforms authenticate domains via DNS records. Brevo requires three records: a Brevo-specific verification code, DKIM, and DMARC. Mailtrap follows the same DNS standards – SPF, DKIM, DMARC.

If you already have DKIM and DMARC configured for Brevo, you’ll add Mailtrap-specific DNS records alongside them. The underlying standards are identical.RC 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

Brevo equivalent: N/A – single endpoint, single SMTP host

Brevo routes all transactional email through one API endpoint (/v3/smtp/email) and one SMTP host (smtp-relay.brevo.com). There’s no built-in separation between transactional and bulk transactional email.

Mailtrap separates these 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

Brevo equivalent: Tags (array of strings)

Brevo uses tags, an array of strings in the API request, for categorizing emails and filtering webhook events. You can attach multiple tags per message.

Mailtrap uses Email Categories, set via the category field in the API or the X-MT-Category header in SMTP.

Key difference: Brevo supports multiple tags per message; Mailtrap assigns one category per message.

Organization & sub-accounts

Brevo equivalent: Users & User permissions (Owner, Admin, and custom roles on Enterprise)

Brevo manages access through a Users system under account settings, with role-based permissions available on higher-tier plans.

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 from the Business plan onward.

Terminology comparison

API migration

Authentication

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

Simple header rename. But there’s one thing to watch: Brevo uses different credentials for SMTP and API. Mailtrap uses the same API token for both.

API mapping

Outbound Sending API JSON Field Mapping

Code snippets

Note: The payloads are similar in shape, both use flat JSON with sender/recipient objects. The main differences are: 

• A different auth header
• Brevo uses sender (Mailtrap uses from) 
• Brevo uses htmlContent/textContent (Mailtrap uses html/text) 
• Brevo uses tags array (Mailtrap uses single category)

SMTP migration

Migration notes:

• Host: Replace smtp-relay.brevo.com with the appropriate Mailtrap host. If you send both transactional and bulk email, you now need two separate SMTP configurations instead of one.
• Username: Brevo provides a unique email address as the SMTP login. Mailtrap uses the literal string api.
• Password: Brevo uses a dedicated SMTP key (different from the API key). Mailtrap uses the same API token for both SMTP and API – one credential to manage.
• Port 465: Brevo supports implicit SSL/TLS on port 465. Mailtrap does not – use port 587 with STARTTLS instead.

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

Rate limits & quotas

Key difference: Brevo’s rate limits are significantly higher on paper (1,000+ RPS), but this is the ceiling; the actual throughput depends on your plan. Brevo’s free plan is also heavily capped at 300 emails/day with no rollover.

Email templates

This is where the migration gets interesting. Brevo uses the Brevo Template Language (based on Pongo2/Django template syntax). Mailtrap uses Handlebars. The {{ }} delimiters look similar, but the syntax is not compatible – you’ll need to convert templates.

Syntax comparison

Template conversion guide

Converting Brevo templates to Mailtrap Handlebars requires these changes:

1. Remove params. prefix: Brevo references variables as {{ params.name }}; Mailtrap uses {{name}} directly.

2. Convert conditionals: Brevo’s {% if %}...{% endif %} becomes {{#if}}...{{/if}}.

# Brevo
{% if params.hasOrder %}Order confirmed{% endif %}


# Mailtrap
{{#if hasOrder}}Order confirmed{{/if}}

3. Convert loops: Brevo’s {% for %}...{% endfor %} becomes {{#each}}...{{/each}}.

# Brevo
{% for item in params.items %}{{ item.name }}{% endfor %}


# Mailtrap
{{#each items}}{{this.name}}{{/each}}

4. Convert default values: Brevo’s | default:"value" filter becomes a Handlebars {{#if}}...{{else}} block.

# Brevo
{{ params.name | default:"there" }}


# Mailtrap
{{#if name}}{{name}}{{else}}there{{/if}}

5. Rename API field: Change params to template_variables in your send call, and change templateId to template_uuid.