Migrate from SendGrid to Unitpost

Before you start

• A SendGrid API key with Full Access, or a Restricted Access key with the read scopes listed under the key field in Settings → Migration. A narrower key skips whatever it cannot read.
• A Unitpost API key with emails:send for your app, created in API keys.
• A second Unitpost key for the migration steps, with templates:write, topics:read, topics:write and webhooks:manage, saved as UNITPOST_MIGRATION_KEY. Keep it out of your app and revoke it once the move is done.
• Access to your DNS host.
• If you use subusers, a decision on which workspace each one becomes.

The cut-over plan

SendGrid keeps sending until the last step, so there is no gap in delivery.

1. 1

   Run the Migration Assistant

   Paste the key in Settings → Migration. The snapshot waits on SendGrid's contact export jobs, so a large account takes longer. In the preview's suppression list, SendGrid blocks show as other: exclude the ones you still want to mail before you accept. Suppressions are written before contacts, so globally unsubscribed contacts land unsubscribed.

2. 2

   Copy unsubscribe-group opt-outs

   Do this before any campaign scoped to a topic. Read every group unsubscribe from GET /v3/asm/suppressions and opt those addresses out of the matching topic with POST /api/v1/email/topics/{id}/opt-out. Each address must already be a contact here: the call refuses the whole list at the first one that is not.

   copy-group-unsubscribes.mjs

   import { Unitpost } from "unitpost";
   
   const unitpost = new Unitpost(process.env.UNITPOST_MIGRATION_KEY);
   
   // 1. Every group unsubscribe: one row per address per group.
   const rows = await fetch("https://api.sendgrid.com/v3/asm/suppressions", {
     headers: { Authorization: "Bearer " + process.env.SENDGRID_API_KEY },
   }).then((r) => r.json());
   
   // 2. The importer named each topic after its unsubscribe group.
   for await (const topic of unitpost.email.topics.listAll()) {
     const emails = rows
       .filter((r) => r.group_name === topic.name)
       .map((r) => r.email.toLowerCase());
     for (let i = 0; i < emails.length; i += 1000) {
       const { error } = await unitpost.email.topics.optOut(topic.id, {
         emails: emails.slice(i, i + 1000),
       });
       if (error) throw new Error(topic.name + ": " + error.message);
     }
   }

3. 3

   Verify your domains next to SendGrid

   Open Domains and publish the records shown: MX and SPF on unitpost.<your domain> and a DKIM TXT under _domainkey. SendGrid's em and s1/s2._domainkey CNAMEs stay where they are, so both providers verify at once. Keep your single _dmarc record.

4. 4

   Port dynamic templates

   Unitpost fills {{name}} placeholders only, with no loops or conditionals, so render {{#each}} tables in your code or split the template. first_name, last_name, email and unsubscribe_url are reserved and fill per recipient, so rename variables that use them and replace {{{unsubscribe}}} with {{unsubscribe_url}}. Imports land as marketing drafts, which adds a footer: set receipts and resets to transactional and publish with PATCH /api/v1/email/templates/{id}.

5. 5

   Switch the SDK

   The display name moves into from (Acme <hi@acme.com>). A template send passes template: { id, variables } with Unitpost's tmpl_ id instead of template_id and dynamic_template_data, and scheduled_at (ISO 8601, up to 90 days ahead) replaces the Unix send_at, which SendGrid caps at 72 hours. Sends also accept an Idempotency-Key, which SendGrid does not offer.

   send.ts

   // Before: SendGrid
   const sgMail = require("@sendgrid/mail");
   sgMail.setApiKey(process.env.SENDGRID_API_KEY);
   await sgMail.send({
     to: "user@example.com",
     from: "hi@acme.com",
     subject: "Your receipt",
     html: receiptHtml,
   });
   
   // After: Unitpost
   import { Unitpost } from "unitpost";
   const unitpost = new Unitpost(process.env.UNITPOST_API_KEY);
   const { data, error } = await unitpost.email.send({
     to: "user@example.com",
     from: "Acme <hi@acme.com>",
     subject: "Your receipt",
     html: receiptHtml,
   });

6. 6

   Replace the webhook verifier

   SendGrid's Signed Event Webhook is checked against a public key; Unitpost signs each delivery with a per-endpoint whsec_ secret in the svix format, one event per request with a type field. Rotate the secret in Webhooks to see it, deploy the new verifier, then set status to enabled. A switched-off endpoint does not queue events.

7. 7

   Send tests

   Send each template once with POST /api/v1/email/templates/{id}/test-send, and fire POST /api/v1/webhooks/{id}/test at the endpoint.

8. 8

   Move traffic in stages

   Move one message type first and watch email.bounced and email.complained for it, then the rest. SendGrid stays verified, so rolling back is a config change.

9. 9

   Cancel SendGrid last

   Re-run step 2 on cut-over day, finish the checks below, then downgrade or close the account.

Before you cancel SendGrid

• Export contacts and suppression lists as files before you downgrade or close: when SendGrid retired its free plans, accounts left on them with more than 100 contacts had their contacts deleted.
• Download the Email Activity you need; SendGrid keeps up to 30 days of it only with its Email Activity history add-on, and none of it moves.
• Re-run the group unsubscribe copy (step 2) so late opt-outs reach Unitpost.
• Delete SendGrid's em CNAME and s1._domainkey and s2._domainkey CNAMEs once no mail goes through SendGrid. Keep _dmarc and Unitpost's records.
• Delete SendGrid API keys and switch off its Event Webhooks.

Facts about SendGrid checked 2026-11-02. Providers change their APIs and plans; check their docs before you rely on a detail.