Migrate from SendGrid

A transactional migration is a release, not a campaign

Marketing migrations fail loudly: somebody notices the wrong offer. Transactional migrations fail quietly. A password reset that never arrives, an invoice that goes to spam, a delivery notification that stops after the third retry — these are discovered by customers, not by dashboards, and usually hours after the change. That is why the work has to be run like a deployment: one change at a time, a measurable blast radius, a rollback that somebody has rehearsed, and an owner who is awake.

The shape of the release is simple. Freeze the contract your application depends on, which is not the template but the set of variables and the response your code expects. Inventory every call path. Rebuild and test templates against the contract. Send a small slice through the new provider while the old one still carries the rest. Then shift traffic in stages, watching delivery, latency and errors at each step.

What makes this different from a normal release is that the output leaves your infrastructure and enters somebody else’s inbox. You cannot roll back a message that was already delivered to a customer, and you cannot un-send a broken link. So the rollback plan has to distinguish between the part you control, which is routing, and the part you do not, which is what already landed. Say that in the kickoff, because a team that believes rollback is total will take risks it should not.

The inventory an engineer should produce

Start with the code, not the dashboard. Search the repositories for the provider’s hostname and for every wrapper around it, then list each service that sends: application, checkout, identity, support tooling, cron jobs, and the one lambda nobody remembers. For each, record the credential it uses, the template or inline body it sends, the volume per day, and the consequence if it stops. The consequence column is what tells you which paths can ship on day four and which need a dedicated test.

Then inventory the platform side. API keys and their scopes, template identifiers and versions, webhook endpoints and the events they subscribe to, event consumers such as a warehouse ingest or an analytics pipeline, and any dedicated IPs with their current reputation. The migration notes we work from list the same set, and the reason is that each item is a dependency somebody will otherwise discover during cutover.

Write the inventory as a table with an owner per row. The exercise takes an afternoon for a small engineering team and a day for a platform with several services. It is also the document you will return to when somebody asks, three weeks after cutover, why a particular notification stopped, and the honest answer needs to be found in minutes rather than reconstructed from memory.

Templates are an interface: freeze the variables

A transactional template is an interface between your application and a customer, and the variable names are the contract. Freeze that contract before anything else: the exact field names, their types, which ones are optional, and what the template renders when one is missing. Then rebuild the template against the frozen contract rather than rebuilding the contract around whatever the new editor happens to offer. This is the single discipline that prevents the classic post-migration defect, a receipt that says Hello and then nothing.

Variable behaviour is where platforms differ most. Some treat a missing value as empty, some fail the send, some render a fallback you defined earlier. You need to know which, per template, before you go live. Build a test payload for every template with three variants: all fields populated, optional fields missing, and a field containing an awkward value such as an ampersand, an apostrophe or a Devanagari name. Send all three to a seed inbox and keep the screenshots.

Formatting is part of the contract too. Currency should render with the rupee symbol and Indian digit grouping, dates should be unambiguous, and order identifiers should not be truncated by a column width. If your application computes a formatted string and passes it in, the template does less work and the risk moves into code you can unit test. That is usually the better trade for transactional mail, where a formatting bug is a support call rather than a slightly odd campaign.

Webhooks and event consumers: the hidden dependency

Sending mail is half the system. The other half is what happens after: delivered, bounced, opened, clicked, complained, unsubscribed. Those events flow to your warehouse, your CRM, your support tool and sometimes your billing logic. A migration that moves the sending but not the event stream looks successful for a day and then produces a silent data gap that finance notices at month end.

Map the pipeline before you move it. Producers emit events, a transport delivers them, consumers process them and sinks store them. Each hop has a failure mode: unsigned webhooks that anybody could post, retries that duplicate a charge, a consumer that acknowledges before it has written to the database, and a dead-letter queue nobody monitors. If the old pipeline had these problems, the migration is a good moment to fix them, but fix them deliberately rather than as a side effect of changing vendors.

Signature verification is not optional. A webhook endpoint that accepts any POST is a way for an attacker to mark an invoice as paid or a contact as unsubscribed. Verify the signature with the shared secret, reject anything that fails, and record the rejection. Then make processing idempotent using the event identifier, so a retry after a timeout does not double-count a delivery or, worse, double-credit an account. These are ordinary engineering habits, and they are the reason transactional migrations take longer than the demo suggests.

API keys, scopes and the credential you should not reuse

The old account probably has one key that does everything, created by somebody who left, pasted into three services and never rotated. It works, which is exactly why it survived. Do not carry that pattern into the new platform. Create one key per service, scope it to the minimum it needs, store it in a secret manager rather than an environment file on a laptop, and give it a name that says which service owns it. When something goes wrong at 2am, the name is what tells you which service to look at.

Key rotation is a habit, not an event. Decide a rotation interval, document who can rotate, and prove the procedure once before you need it. A key that cannot be rotated without a deploy is a key that will never be rotated, and an incident will eventually force the change at the worst possible moment. The same applies to webhook signing secrets: two active secrets during a rotation window, one retired afterwards.

Revocation is part of the cutover, not an afterthought. Keep the old credentials alive while the fallback path exists, then revoke them on a scheduled date with a named owner, and record the date in the runbook. Credentials that outlive the vendor relationship are an access path nobody is watching, and they are the first thing a security review will ask about six months later.

Domain and IP warm-up for mail nobody opted into

Transactional mail has an advantage and a trap. The advantage is that recipients asked for it, so engagement is high and inbox providers learn quickly. The trap is that volume is spiky and often invisible: a payment retry storm, a batch of invoices at midnight, a migration that triggers every welcome email at once. A new domain or IP that meets a spike on day one looks like a compromised sender, and recovery takes weeks.

Warm with the traffic you can control. Start with the lowest-volume, highest-engagement path — password resets and order confirmations for a small slice — and increase while delivery holds. Do not begin with a month-end invoice run. If you have a dedicated IP, it starts with no reputation at all, which is not the same as a bad reputation but is not better either; a small volume on a dedicated IP can be worse than a shared pool until there is history. Our comparison pages are honest that a mature transactional API at global scale is SendGrid’s strength, and reputation is part of what you are leaving behind.

Keep marketing and transactional on separate subdomains and, where possible, separate IPs, so that a campaign with a bad list does not damage password resets. This is one of the few architectural decisions in email that is almost always worth the extra configuration, and it is much cheaper to do during a migration than to retrofit afterwards.

The canary: percentage rollout with a kill switch

A canary for email means sending a defined percentage of a defined class of mail through the new provider while the old one carries the rest. Start with a class that is easy to reason about, such as order confirmations for one region, rather than a random percentage of everything. A random split gives you a representative sample but no clean comparison, and when something breaks you cannot tell which class broke.

The kill switch matters more than the percentage. Decide in advance what makes you stop: a rise in hard bounces, a rise in complaints, a latency increase on the API, a spike in support tickets mentioning receipts, or a rendering defect in a single template. Write the threshold down, name the person who can pull the switch, and make sure the switch is a routing change rather than a code deploy. If stopping requires a release, you will hesitate, and hesitation is how a small defect becomes a bad week.

Expect the comparison to be messy. Different providers report delivery on different clocks, and a delivered event on one side may arrive seconds later than on the other. Compare over a window rather than instantaneously, use the same recipient class, and prefer outcomes that are hard to fake: inbox placement in a seed panel, bounce classification, and the support ticket count. Open rates are noise in a two-day window.

Fallback routing that works at two in the morning

A fallback is only a control if it has been executed. The common version is a diagram that says if the primary fails, traffic goes to the secondary, drawn by somebody who has never tested it. When the primary actually fails, the secondary turns out to need a credential that expired, a template that was never ported, or a DNS record that points at the wrong place. Test the failover during business hours, with a real message, and time how long it takes.

Design the routing so that failover is a decision rather than an accident. A timeout or a run of server errors should trigger an automatic route for a defined class of mail, while a quality problem such as a bounce spike should require a human decision. Automatic failover on quality metrics produces flapping, and flapping between two providers is worse than staying with one that is behaving imperfectly.

Then reconcile afterwards. Messages sent through two paths have two sets of identifiers, and your analytics will double-count unless you key on your own message identifier rather than the provider’s. Decide before cutover which identifier is canonical, store both, and make the warehouse view deduplicate on yours. That single decision prevents a month of confusing dashboards and an argument about whether volume actually doubled.

Bounces, complaints and the loops that must stay closed

Transactional mail still needs suppression, and teams forget that because they think of it as utility. A hard bounce on a receipt must be recorded, or the next receipt bounces too and the address keeps costing you reputation. A complaint on a delivery notification is unusual but real, and it should remove the address from marketing at minimum. An unsubscribe request that arrives through the preference centre must propagate to every class of mail that is legally marketing.

Feed the events back into one place. The pipeline from the webhook section is the mechanism: delivered, bounced, deferred and complained events land in a store, and a job applies them to the suppression list with a source and a timestamp. If the old provider had a suppression list you relied on, export it and apply it before the first send, exactly as you would for a marketing migration. Utility mail is not exempt from the obligation to stop mailing somebody who asked you to stop.

Watch the classification rather than the raw count. A rise in hard bounces is usually a list quality problem and a signal that a form is accepting junk. A rise in deferrals is usually reputation or throttling and a signal to slow down. A complaint is a content or consent signal, not a technical one. Reading a bounce dashboard as a single number produces the wrong fix, which is why the runbook should name the three categories separately.

DPDP adds an obligation that transactional teams routinely miss. Erasure is not limited to marketing lists: if a data principal asks for their data to be removed, the request has to reach the CRM, the warehouse and the sending platform, including the logs that record which address received which message. Decide who owns that workflow before cutover, test it once with a synthetic contact, and keep the erasure record beside the suppression entry so the two do not contradict each other. An erasure request that stops at the email list while the address survives in an event log is not an erasure.

India specifics: GST, residency and the OTP fallback

Two commercial details change when you move to an Indian vendor. The first is the invoice: LoopNow prices in INR and excludes 18% GST, and every payment produces a GSTIN invoice, which matters if you claim input credit. The second is where the data sits, and our published position is AWS Mumbai in ap-south-1. If your security questionnaire asks where message content and recipient data are stored, that is the answer to put in front of your DPO rather than a paragraph about global infrastructure.

Transactional flows also tend to have an SMS or WhatsApp fallback, and that is where Indian registration rules arrive. Commercial SMS needs a registered header and pre-approved templates on the DLT platform, tied to a consent purpose. WhatsApp templates need approval before they can be sent, and a template approved on one business account does not automatically exist on another. Neither is a configuration step you can complete on cutover night, so treat both as lead-time items on the plan, and verify current fees and rejection reasons in the operator portals.

One more practical point about OTPs. Authentication messages are the most sensitive class in the system: a delay of thirty seconds is a failed login, and a filtered message is a support call. Do not move authentication traffic first. Move it last, after the domain has history, and keep the old provider's path warm until you have seen a full week of successful deliveries at your real peak. The order protects the one flow where a small regression is immediately visible to every user.

The capacity conversation nobody has before cutover

Transactional volume is uneven in a way that marketing volume is not. A month-end invoice run, a payment retry campaign or a festive sale can multiply daily sends in an hour, and the plan you bought against an average will hit an overage exactly when you least want a surprise. Before cutover, plot your daily send volume for the last ninety days and mark the three highest days. Size against the peak, not the mean.

LoopNow plans include a monthly email allowance and bill overage per delivered email at the published rate, with a spend cap on by default so that a spike produces a stop or an approved top-up rather than an invoice nobody expected. Compare that with the old provider’s model on the same basis: cost per delivered message at your peak, not at your average. The arithmetic matters more than the headline because transactional peaks are where the difference lives.

Write the capacity decision into the runbook with a number and an owner. If the invoice run on the twenty-eighth is projected to exceed the allowance, either raise the plan for that month or throttle the batch. Both are legitimate; discovering it on the twenty-ninth is not. The same paragraph should say who can approve an overage and how quickly, because a spend cap that nobody knows how to lift becomes an outage during a sale.

What does not port, and the effort nobody budgets

Event history does not move. Delivery logs, bounce reasons and engagement history from the old provider stay where they are, so export what you need for audit or dispute resolution before the account closes. IP reputation does not move either, and neither does the accumulated trust of a domain you no longer control. Template content can be rebuilt against a frozen contract, but the integration surface is new code, not a configuration change: endpoint, authentication, payload shape, error semantics and rate limits all differ.

The effort is therefore in three places, and only one of them is email. Integration work is the largest: a service that sends through a wrapper, a webhook consumer that verifies signatures, an idempotency scheme and a reconciliation view. Template work is a day or two per handful of templates if the contract is frozen. Operational work — warm-up, canary, fallback test, suppression sync — is where the calendar goes, and it cannot be compressed by adding engineers because it is bounded by elapsed time and by how fast inbox providers form an opinion of you.

Be equally clear about the reason to move. If your only need is the cheapest possible API at global scale, a pure transactional provider is a legitimate answer and our own comparison says so. The case for moving is a single bill for email, WhatsApp, voice and workflow, INR pricing with GST invoices, Mumbai residency, and a consent ledger that treats transactional and marketing mail as one relationship rather than two systems that never speak.