Sign inGet Started

Migrate from another provider

Use this guide to move production email from another provider. Map the send request, publish DNS records, import suppressions, translate webhook events, and test the integration before directing production traffic to Bird.

The migration checklist:

  1. Map your send call to POST /v1/email/messages
  2. Re-point your sending domains and DNS
  3. Import your suppression list
  4. Switch webhooks to our event vocabulary
  5. Verify against the mail sandbox before cutover

Steps 1, 3, and 4 depend on which provider you're leaving. Your provider guide has the field-by-field payload mapping, where to export your suppression list, and the webhook event-name translation table.

1. Map the send call

We have one single-send endpoint, POST /v1/email/messages. You build a flat JSON payload (no personalizations wrapper, no MIME assembly) with from, to/cc/bcc arrays, subject, html and/or text, an optional reply_to list, and headers for custom email headers. A successful send returns 202 Accepted with an em_-prefixed message ID. Delivery outcomes arrive asynchronously through webhooks and the read endpoints. The full payload, with every field cap and default, is in Sending email. The field-by-field mapping from your current payload is in your provider guide. If your application submits over SMTP today, you may not need to port the call at all: we accept SMTP submission into the same pipeline, which turns this step into a credentials swap.

Use tags for filter dimensions in message lists, analytics, and dashboard rollups. Use metadata for structured context that Bird stores on the message and returns on API reads. Webhook events can also carry this context, but unsubscribe events can return null values. See Tags vs metadata for limits.

Before you port code, account for these differences:

  • Scheduling, stored templates, and attachments all port. Use scheduled_at for scheduled sending. Use template instead of inline content for stored templates. Map files to the attachments array.
  • Suppressed recipients are rejected, visibly. A suppressed address still gets a recipient_id and appears in the message's recipient list with status rejected and an email.rejected event (rejection_reason: recipient_suppressed), never a silent drop. Even when every recipient is suppressed, the request is still accepted with a 202. Each recipient comes back rejected. See Suppressions.
  • Set category: "transactional" for operational mail. A send defaults to marketing, and the category controls suppression policy: marketing blocks on complaints and unsubscribes, transactional delivers through them. Newsletters and campaigns are handled correctly by the default. Mark receipts, password resets, and similar operational mail transactional so they are not gated by an unsubscribe.

2. Re-point domains and DNS

Register each sending domain with POST /v1/email/domains or in Email > Domains, then publish the records from dns_records. DKIM, the return-path CNAME, and a DMARC policy gate sending. An existing DMARC record, including one at a parent domain, counts. The tracking CNAME gates only branded open and click tracking. Sending domains covers the records, verification lifecycle, and regional model. Use the DNS record splitter if your provider requires a split DKIM value, and the DMARC policy generator if you need a policy.

One record most providers make you start with is deliberately absent: you publish no SPF record at your domain apex. SPF is evaluated against the envelope-from domain, which the return-path CNAME points at us, so SPF passes and aligns without touching your apex. If your old provider had you add an include: to your apex SPF record, leave it in place during the transition and remove it after cutover. It neither helps nor hurts mail sent through us, and removing it frees one of the 10 DNS lookups apex SPF allows. The full explanation is in DKIM, SPF & DMARC.

You can publish our records while your old provider's records are still live. The DKIM record uses a selector of ours. The return-path and tracking CNAMEs are new hostnames you choose, and your existing DMARC record satisfies the gate as-is. Both providers authenticate side by side until you're ready to switch traffic. Domain state is regional, so register the domain in every region you send from.

3. Import suppressions

Carry your suppression list over before sending production traffic through us. Otherwise your first sends go to addresses that already bounced or complained at your old provider, which damages the reputation you're trying to protect.

Export the list from your current provider (your provider guide has the exact endpoints), then add each address here with POST /v1/email/suppressions:

Code example
while read -r address; do
  curl -s -X POST https://us1.platform.bird.com/v1/email/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$address\"}"
done < suppressions.txt

Two things to know about this import path:

  • You import one address per request. The suppressions API is single-entry CRUD, so a large list means looping over the exported addresses. The call is idempotent (201 for a new record, 200 with the existing record if the address is already manually suppressed), so re-running a partial import is safe.
  • Imported addresses get reason: manual, applies_to: all, which blocks every category, including transactional. That is stricter than a native complaint record, which blocks only non-transactional sends, so if you need the category-aware behavior for specific addresses, see the reason taxonomy in Suppressions.

Going forward, hard bounces create workspace suppressions and emit email_suppression.created, regardless of Brand attribution. Complaints without reliable Brand attribution also create workspace suppressions and emit email_suppression.created. Brand-attributed complaints record protected preferences. Unsubscribes record preferences. Subscribe to preference events as well, even for a workspace with one Brand, so your system mirrors these opt-outs and later grants. The message-level email.complained, email.unsubscribed, and email.list_unsubscribed events remain available. See Email events for the distinction.

4. Switch webhooks

Register an endpoint with POST /v1/webhooks and subscribe it to an explicit list of event types. Our event names follow resource.action: email.accepted → email.processed → email.delivered on the happy path, with email.deferred, email.bounced, email.complained, email.rejected, email.opened, email.clicked, and the unsubscribe pair covering the rest. The event-name translation from your current provider's vocabulary is in your provider guide. Per-event payload schemas are in the events reference.

Correlate outbound message events using email_id and workspace_id; recipient lifecycle events also carry recipient_id. Store that message-to-customer mapping when you send. Treat tags and metadata as extra context when present: email.unsubscribed and email.list_unsubscribed from Bird unsubscribe links return null values for individual sends, even when the send included them. Broadcast unsubscribe events can also return null when that context is unavailable.

Use preference.revoked, preference.granted, and preference.deleted as signals to refresh your preference mirror. These events identify preference_id and transition_id, with channel, handle, Brand, sender, and topic scope; they do not carry message IDs or send metadata. Their timestamp is the statement's effective time, not a record version. A delayed complaint can revoke a later bulk grant, and different changes can share a timestamp. Do not choose the current status or coverage by sorting events or treating transition_id as an ordering sequence.

Initialize and maintain a complete preference mirror in this order:

  1. Subscribe to preference events and durably retain incoming notifications before starting the initial read.
  2. Seed the mirror from every page of the workspace preference list, without channel, handle, or Brand filters. This discovers existing opt-outs that have never generated a notification for your endpoint. Keep each record's ID, channel, handle, Brand, sender, and topic scope.
  3. Process retained and new notifications by fetching the current preference and listing the affected channel and handle through every page. Compare scopes to account for deletion and recreation under a different ID. Periodically reconcile the complete unfiltered workspace list as well, including recipients absent from notifications or your local mirror.

Reads can lag a change: retry transient errors and unexpected missing or older state. A failed or incomplete read must not clear a local block. Remove a deleted record only after confirming its absence; preserve independent preferences and suppressions. This mirror converges over time and does not replace Bird's send-time checks.

email_suppression.created identifies additions by suppression_id, workspace_id, and email. There is no customer suppression-deletion event. To discover removals made in the dashboard or API, periodically read the workspace suppression list through every page and reconcile by suppression ID. Do not remove records after a failed or partial scan; confirm missing records on a subsequent read before removing them. Keep suppression records separate from preferences so removing one block cannot clear another.

We sign deliveries per the Standard Webhooks specification, using three headers: webhook-id, webhook-timestamp, and webhook-signature, with an HMAC-SHA256 over {id}.{timestamp}.{raw body}. If you already verify Standard Webhooks deliveries from another platform, the exact same verification code works here. Otherwise, the verification recipe, retry schedule, and replay tooling are in Webhooks & events. Deliveries are at-least-once and unordered, so deduplicate on webhook-id. Use message-event timestamps to display message chronology; use current-state reconciliation for preferences and suppressions as described above.

5. Verify in the sandbox before cutover

Before you move production traffic, exercise the ported send call and message-event handler against the mail sandbox. Sandbox sends go to magic addresses at messagebird.dev and run through the real production pipeline: same 202, same event sequence, same signed webhook deliveries, without ever reaching an inbox or touching your reputation.

Sandbox signals do not write suppression or complaint-preference records. Test your mirror separately with representative email_suppression.created, preference.revoked, preference.granted, and preference.deleted payloads from the webhook event contracts, including two Brands sharing the same recipient. Include these cases:

  • An unchanged opt-out predates webhook registration. The initial unfiltered inventory discovers it without a notification; periodic inventory also discovers a record missing from your local mirror.
  • An individual-send unsubscribe has null tags and metadata; your saved message mapping still identifies the customer.
  • A complaint arrives after a newer bulk grant, or an older all-category opt-out broadens complaint protection without advancing its effective timestamp. Deliver the events in reverse order and verify that reconciliation retains the current revoked status and coverage.
  • A preference is deleted and recreated, or a manual suppression is removed in the dashboard. Reconciliation removes only records confirmed absent and retains unrelated blocks.
  • A refresh fails or temporarily returns older state. Your handler retries and periodic reconciliation repairs the mirror without clearing blocks on the failed read.

A minimal pre-cutover smoke test:

  1. Send to delivered@messagebird.dev and assert your handler processes email.accepted → email.processed → email.delivered.
  2. Send to bounce@messagebird.dev and assert your bounce handling fires on email.bounced (simulated bounces don't write to your suppression list, so the address stays reusable).
  3. Send to suppressed@messagebird.dev and assert you handle email.accepted followed by email.rejected, with no email.processed or delivery events after it. That is the shape every suppressed recipient produces in production; the rejection_reason: recipient_suppressed detail is on the recipient record and the events API.
  4. Send a category: "marketing" message and confirm the category shows up where you expect on the message read.

Use +label subaddressing (bounce+cutover-test@messagebird.dev) to correlate test cases. The full address appears in your events. Once the smoke test passes, cut traffic over. Point your application at us, and keep the old provider's DNS in place until your domains here show capabilities.sending verified. Watch the first hours of real deliveries in the dashboard and your webhook stream.

Migrating from a specific provider

  • SparkPost: transmissions and SMTP, template conversion, scoped suppressions, and webhook events
  • SendGrid: personalizations → flat payload, categories/custom_args → tags/metadata, the dropped ↔ email.rejected equivalence
  • Mailgun: o:*/v:*/h:* parameters → first-class fields, bounces/complaints/unsubscribes export
  • Amazon SES: SendEmail v2 → one endpoint, configuration sets → per-message tracking flags, SNS → signed webhooks
  • Resend: near-identical payload shape, Svix-signed webhooks → Standard Webhooks
  • Postmark: comma-separated recipients → arrays, per-stream suppression dumps, unsigned webhooks → signed
  • Brevo: address objects → plain addresses, two separate blocklists to export, params → template.parameters
  • MailerSend: five suppression lists of which the temporary one stays behind, personalization → per-send parameters
  • Mailjet: the Messages array → one flat payload, EventPayload → metadata, blocklist export
  • Mandrill: the message wrapper and body auth → flat payload and bearer auth, rejection blacklist export

Next steps