How to switch transactional email providers without downtime

Switching transactional email providers is mostly not a code change. The send call is usually one helper function. The risk is everything around it: DNS that isn't ready, a sending domain with no history on the new provider, webhooks pointed at the wrong handler, and a suppression list left behind.

The order below keeps password resets, receipts and sign-in codes flowing the whole time. It works whichever providers you are moving between.

1. Set up DNS on the new provider first

Do this days before you change any code. Add your sending domain to the new provider and publish the records it asks for. Typically that is:

Leave every record your old provider uses where it is. Both providers need to be able to send for your domain while you migrate.

A merged SPF record looks like this:

example.com.  TXT  "v=spf1 include:old-provider.example include:spf.groundmail.dev ~all"

Wait until the new provider shows the domain as verified before moving on. Check the DKIM record resolves from outside your network, not only in your DNS host's dashboard.

2. Bring your suppressions and webhooks over

Before any real mail goes out through the new provider:

• Import suppressions. Export hard bounces and spam complaints from the old provider and import them. Otherwise your first days on the new provider re-send to addresses that already bounced, which is the fastest way to hurt a new sending reputation.
• Point webhooks at a handler that understands both formats. Event names and payloads differ between providers. Map both into the same internal events (delivered, bounced, complained) so the rest of your app doesn't care which provider sent a message.
• Store the new provider's message ids. If you match events to sends by id, make sure the column can hold ids from both.

3. Send through both providers behind a flag

Wrap the send helper so you can choose the provider per message:

async function sendEmail(msg: Message) {
  const useNew = await flags.percentage("email-new-provider", msg.to);
  return useNew ? newProvider.send(msg) : oldProvider.send(msg);
}

Key the percentage on the recipient so the same person keeps getting mail from the same provider while you ramp. Start with a small share of traffic, or with one low-risk message type such as internal notifications, and raise it in steps.

At each step, compare the two providers on:

• delivery rate and hard bounces
• spam complaints
• time from API call to delivery for your most time-sensitive messages, such as sign-in codes

If the new provider looks worse at any step, hold the percentage where it is and find out why before going further. Common causes are a DNS record that isn't aligned, or a suppression list that wasn't imported.

4. Cut over, and keep a rollback

When the new provider has carried most of your traffic for several days at normal volume and the numbers look normal, set the flag to 100%.

Don't remove the old provider yet. Keep its API key active and its DNS records published for a week or two, so rolling back is a flag change rather than an emergency DNS edit.

5. Clean up

Once you're confident:

1. Remove the old code path and the flag.
2. Revoke the old provider's API keys and SMTP credentials.
3. Delete its DKIM record and return-path record.
4. Remove its include from your SPF record.

That last step matters. Every include in an SPF record counts toward the limit of 10 DNS lookups, and stale includes are a common reason SPF starts failing months later.

If you're moving to Groundmail

Groundmail follows the same plan. Verify your domain first, import suppressions with the API, and send through both providers until you're ready. Our migration guides walk through the field mapping for specific providers, and the quickstart covers the first send.