SendboundSendbound

Migration Guide

Move from SendGrid, Mailgun, Postmark, or AWS SES to Sendbound. Parallel-run strategy, DNS cutover, and rollback plan included.

This guide covers the full migration playbook — from audit to cutover — regardless of which provider you're leaving.

Provider-specific instructions:

The migration playbook

Every provider migration follows the same four phases. The key principle: run Sendbound in parallel with your existing provider before you cut over. This keeps risk near zero.

Phase 1 — Audit (30 minutes)

Before touching any code, take stock of what you're moving:

AssetWhere to find itWhat to do
Sending domainsYour provider's domain/identity settingsNote which domains you send from
TemplatesTemplate library in your provider's UIExport as HTML or MJML
Contacts / listsContacts or audiences sectionExport as CSV
WebhooksDeveloper or webhook settingsNote the endpoint URLs and event types
Suppression listsUnsubscribes / bounces sectionExport — these import first to protect your list

Export your suppression list (bounces + unsubscribes) before importing contacts. Sendbound will honour existing suppressions and won't send to addresses that previously bounced hard.

Phase 2 — Configure Sendbound (15–30 minutes)

Set up Sendbound while your old provider stays live.

2a. Verify your sending domain

Add your domain in Settings → Domains. Sendbound generates three DNS records:

RecordTypePurpose
sendbound._domainkey.yourdomain.comTXTDKIM signing
yourdomain.comTXTSPF authorisation
_dmarc.yourdomain.comTXTDMARC policy

Add these to your DNS provider and click Verify. DNS propagation typically takes 2–10 minutes.

Your existing SPF record may already have include: statements. Add include:sendbound.com to the existing record — do not create a second SPF TXT record. Domains with two SPF records fail validation.

2b. Get your API key

Go to Developer → API Keys, create a new key, and copy the sk_live_... value.

2c. Import your suppression list

Upload bounces and unsubscribes before contacts to prevent sending to known-bad addresses.

2d. Import contacts

Upload your contact CSV. Map columns to Sendbound fields — email, firstName, lastName, and any custom attributes. Sendbound preserves unsubscribe status from the CSV if you include an unsubscribed column.

2e. Import templates

Open the template editor and use Import → MJML / HTML to paste or upload each template. Sendbound renders a live preview as you import.

2f. Configure webhooks

Add your existing webhook endpoint in Developer → Webhooks. Select the events you want (delivered, bounced, opened, clicked, complained, unsubscribed). Save the signing secret for HMAC verification.

Phase 3 — Parallel run (1–7 days)

Deploy your code update so both providers handle email simultaneously. This is the safest way to migrate:

// Feature flag controls which provider is primary
const EMAIL_PROVIDER = process.env.EMAIL_PROVIDER ?? 'sendgrid';

async function sendEmail(opts: EmailOptions) {
  if (EMAIL_PROVIDER === 'sendbound') {
    return sendViaSendbound(opts);
  }
  return sendViaOldProvider(opts);
}

During the parallel run:

  • Monitor the Sendbound dashboard for delivery confirmations
  • Compare inbox placement rates in Analytics → Deliverability
  • Watch for any bounce or complaint spikes

Run for at least 24–48 hours before cutting over. Longer is better for low-volume senders where statistical significance takes time.

Phase 4 — Cutover

When you're confident:

  1. Set EMAIL_PROVIDER=sendbound in production and remove the old provider fallback
  2. Remove the old SDK dependency from your package.json
  3. Revoke your old provider API key
  4. Cancel your old plan (keep credentials until billing cycle ends in case you need to check historical logs)
  5. Monitor Sendbound analytics for 24 hours post-cutover

Rollback plan

If something goes wrong during cutover, rollback is instant:

# Revert the environment variable — no code deploy needed
EMAIL_PROVIDER=sendgrid

Because your old provider's DNS records and API key are still intact during the parallel run window, you can switch back in under a minute.

DNS considerations

SPF

SPF records are TXT records on your root domain. Add include:sendbound.com to your existing SPF record:

# Before
v=spf1 include:sendgrid.net ~all

# After (keep old include during parallel run, remove after cutover)
v=spf1 include:sendgrid.net include:sendbound.com ~all

After cutover, remove the old provider's include statement.

DKIM

DKIM is a separate DNS record at a subdomain (sendbound._domainkey.yourdomain.com). It does not conflict with your existing provider's DKIM records — you can have multiple DKIM keys simultaneously.

DMARC

If you don't have a DMARC record yet, add one during migration. Start in reporting mode:

_dmarc.yourdomain.com TXT "v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com"

Once Sendbound is your only provider and you've confirmed DKIM and SPF alignment, tighten the policy:

_dmarc.yourdomain.com TXT "v=DMARC1; p=quarantine; pct=100; rua=mailto:dmarc@yourdomain.com"

Webhook event mapping

Sendbound event names and their equivalents in common providers:

Sendbound eventSendGridMailgunPostmark
email.delivereddelivereddeliveredDelivery
email.openedopenopenedOpen
email.clickedclickclickedClick
email.bouncedbouncefailedBounce
email.complainedspamreportcomplainedSpamComplaint
email.unsubscribedunsubscribeunsubscribed—

Need help?

SDKs & Libraries

Official SDKs, the MCP server, and the OpenAPI spec for the Sendbound API.

Migrate from SendGrid

Step-by-step guide to moving from Twilio SendGrid to Sendbound. API mapping, template porting, webhook translation, and parallel-run strategy.

On this page

The migration playbookPhase 1 — Audit (30 minutes)Phase 2 — Configure Sendbound (15–30 minutes)Phase 3 — Parallel run (1–7 days)Phase 4 — CutoverRollback planDNS considerationsSPFDKIMDMARCWebhook event mappingNeed help?