Migrate from SendGrid to Bird.

Email is mostly DNS and IP reputation. This playbook walks the seven-section path: concept map, side-by-side send, the DKIM/SPF/DMARC dual-publish plan, the 14-day IP-reputation handoff, suppression-list import, webhook event mapping, and the 8-step cutover checklist.

SendGrid surfaces to Bird surfaces.

Most translations are mechanical. Templates, stats, and inbound parsing have direct equivalents; the suppression list comes across via CSV import.

SendGrid	Bird	Note
sgMail.send({ from, to, subject, html })	bird.emails.send({ from, to, subject, html })	Same fields. Bird returns { data, error }.
sgMail.sendMultiple({ ... })	bird.emails.send({ to: [...] })	Array recipient. Up to 500 per call.
client.request({ url: "/v3/templates", ... })	bird.templates.create/get/list/update	Same lifecycle. React Email accepted natively.
client.request({ url: "/v3/suppression/bounces" })	bird.suppressions.list/import	Bird imports your SendGrid CSV as-is.
client.request({ url: "/v3/stats" })	bird.emails.metrics({ from, to, group_by })	Per-domain, per-ISP, per-IP rollups.
Event Webhook (array payload, mixed event types)	bird.webhooks (one event per request, typed)	Single envelope; HMAC-SHA256 signed.
Inbound Parse	bird.emails.inbound (HMAC-signed parser)	One handler per recipient mailbox.

The send path, both shapes.

The fields line up almost one-to-one. The biggest change is the return contract — Bird returns { data, error } destructured instead of throwing.

sendgrid-send.ts

before

import sgMail from "@sendgrid/mail";

sgMail.setApiKey(process.env.SENDGRID_API_KEY!);

try {
  const [response] = await sgMail.send({
    from:    "hello@yourdomain.com",
    to:      "ada@example.com",
    subject: "Your invite is ready",
    html:    "<p>Welcome.</p>",
    customArgs: { event_id: "evt_42" },
  });

  console.log("OK:", response.headers["x-message-id"]);
} catch (err: any) {
  console.error(err.response?.body ?? err);
  throw err;
}

bird-send.ts

after

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const { data, error } = await bird.emails.send({
  from:    "hello@yourdomain.com",
  to:      ["ada@example.com"],
  subject: "Your invite is ready",
  html:    "<p>Welcome.</p>",
  tags:    { event_id: "evt_42" },
}).safe();

if (error) throw error;
console.log("OK:", data.id);
// → "email_2bX91Yk8h..."

Dual-publish DKIM and SPF. Hold DMARC steady.

The risk during an email vendor migration is one of the records going stale and dropping alignment. Lower the TTL first, dual-publish both vendors' records for the warm-up, monitor DMARC aggregate reports, then retire the old selector.

Day 0Lower the TTL on your existing SendGrid DKIM and SPF records to 300 seconds (5 minutes). Wait one full TTL cycle before continuing.
Day 1Add Bird DKIM record at a separate selector (e.g. bird._domainkey) alongside the SendGrid one. Add Bird sending-IP range to your SPF include list. Both vendors now sign valid mail.
Day 1–7Hold DMARC at its current policy (usually p=none or p=quarantine). Watch DMARC aggregate reports for SPF/DKIM alignment failures on either vendor.
Day 7Begin ramping Bird traffic. Day 7 = 10%, Day 9 = 25%, Day 12 = 50%, Day 14 = 100%. The IP-reputation warm-up plan below runs in parallel.
Day 14Remove the SendGrid DKIM selector and SPF include. Bird-only signing. DMARC alignment stays clean.
Day 21Restore the TTL on the surviving records to your normal value (3600+). Decommission the SendGrid account.

Fourteen days. Bird IPs ramp; SendGrid drops.

Bird managed IPs are warmed automatically. During the handoff we route a growing share of your daily volume through Bird so the new IPs build reputation at the rate ISPs trust. Don't rush this — volume spikes on cold IPs land in spam folders.

Day	Bird	SendGrid
Day 1	5%	95%
Day 2	10%	90%
Day 3	15%	85%
Day 4	20%	80%
Day 5	25%	75%
Day 6	30%	70%
Day 7	40%	60%
Day 8	50%	50%
Day 9	60%	40%
Day 10	70%	30%
Day 11	80%	20%
Day 12	90%	10%
Day 13	95%	5%
Day 14	100%	0%

Bring your unsubs, bounces, and spam reports with you.

Export the three CSVs from SendGrid (Global Unsubscribes, Bounces, Spam Reports) and pass them to bird.suppressions.import. The SendGrid header layout is recognized natively; no transformation needed.

import-suppressions.ts

one-shot

import { BirdClient } from "@messagebird/sdk";
import { readFileSync } from "node:fs";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

// Export from SendGrid: Settings → Suppressions → Global Unsubscribes,
// Bounces, Spam Reports — download each as CSV.
const file = readFileSync("./sendgrid-suppressions.csv", "utf8");

const { data, error } = await bird.suppressions.import({
  file,
  format: "csv",
  // Bird accepts the SendGrid header layout natively.
  source: "sendgrid",
});

if (error) throw error;
console.log("Imported:", data.imported_count, "addresses");
// → "Imported: 184,221 addresses"

SendGrid Event Webhook to Bird events.

SendGrid posts an array of mixed event types per webhook. Bird posts one event per request and signs it with HMAC-SHA256 in the Bird-Signature header.

SendGrid event	Bird event
processed	email.queued
delivered	email.delivered
open	email.opened
click	email.clicked
bounce	email.bounced
dropped	email.failed
deferred	email.queued (with reason)
spamreport	email.complained
unsubscribe	email.unsubscribed
group_unsubscribe	email.unsubscribed (with group)

Same names. Same shapes. One envelope.

Single typed event per request, HMAC-SHA256 verified through bird.webhooks.parse.

webhook.ts

signed

// SendGrid Event Webhook payload comes in as an array of events.
// Bird emits one event per webhook call. Same names; same shapes.
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

export async function handler(req: Request) {
  const event = await bird.webhooks.parse(req, {
    secret: process.env.BIRD_WEBHOOK_SECRET!,
  });

  switch (event.type) {
    case "email.delivered":  return handleDelivered(event.data);
    case "email.bounced":    return handleBounce(event.data);
    case "email.opened":     return handleOpen(event.data);
    case "email.clicked":    return handleClick(event.data);
    case "email.complained": return handleComplaint(event.data);
    case "email.unsubscribed": return handleUnsub(event.data);
    default: return new Response(null, { status: 204 });
  }
}

Email migrations are staffed.

Email migrations@bird.com with your sending domain, monthly volume, and current ESP. We'll provision a shared channel and a deliverability engineer for the warm-up window.

Migrate from SendGrid to Bird.

SendGrid surfaces to Bird surfaces.

The send path, both shapes.

Dual-publish DKIM and SPF. Hold DMARC steady.

Fourteen days. Bird IPs ramp; SendGrid drops.

Bring your unsubs, bounces, and spam reports with you.

SendGrid Event Webhook to Bird events.

Same names. Same shapes. One envelope.

Eight steps from domain verification to decommission.

Existing IP reputation is the migration tax.

Email migrations are staffed.

Begin met één kanaal.
Voeg de rest toe wanneer je er klaar voor bent.

Migrate from SendGrid to Bird.

SendGrid surfaces to Bird surfaces.

The send path, both shapes.

Dual-publish DKIM and SPF. Hold DMARC steady.

Fourteen days. Bird IPs ramp; SendGrid drops.

Bring your unsubs, bounces, and spam reports with you.

SendGrid Event Webhook to Bird events.

Same names. Same shapes. One envelope.

Eight steps from domain verification to decommission.

Existing IP reputation is the migration tax.

Email migrations are staffed.

Begin met één kanaal.Voeg de rest toe wanneer je er klaar voor bent.

Begin met één kanaal.
Voeg de rest toe wanneer je er klaar voor bent.