Switching email API providers is one of those projects that looks small and turns out to touch everything: application code, DNS, templates, webhooks, suppression lists, monitoring and, most importantly, your sender reputation. Teams move for good reasons, such as cost structure, support, features, regional needs or consolidation, and the most common failures are avoidable: a lost suppression list, an SPF record that breaks, webhooks that stop updating the database or all traffic moved to a cold IP in one day. This checklist is written for engineers and operations teams planning a move from any provider to any other. It uses generic steps, so it applies whether you are leaving SendGrid, Mailgun, Resend, Postmark, Amazon SES or something else, and whichever service you are moving to. We make a competing service, so use the checklist to test every provider, including us. For help deciding whether to move at all, see Amazon SES alternatives and SendGrid alternatives.
Before you start: decide whether to move
A migration will not fix list quality, content or consent problems. If your issue is complaints or bounces, those follow you to the new provider and you will start with an unknown reputation. Confirm that the cause of your dissatisfaction is something a new provider addresses, such as missing tooling, support or limits. Also avoid moving during your busiest period.
Phase 1: inventory
- List every sender. Application servers, background workers, CMS plugins, billing systems, support tools, monitoring alerts, scripts and legacy services. Search your code and configuration for the old provider's hostname, API base URL and key names.
- List every domain and subdomain used in the From address and the return-path or bounce domain.
- List every credential. API keys, SMTP usernames and where each is stored.
- List every inbound webhook from the provider to your systems: events, endpoints and what each does.
- List every template, tag, category and custom argument your code or reporting depends on.
- Record current volumes and peaks by stream and by hour, so you can plan ramp-up.
- Capture baseline metrics: delivery, bounce, complaint and engagement rates per mailbox provider.
Phase 2: choose and evaluate the new provider
Compare providers against your inventory. Check that the new service supports each sending method you use, the authentication you need, the events your code consumes and the volume you send. Review limits, review processes for new accounts, acceptable use policy and support. Our provider checklist and email API guide list the questions. Do not rely on marketing pages for prices or limits; check current terms and ask in writing.
Phase 3: export and import data
| Data | Why it matters | Notes |
|---|---|---|
| Suppression lists (hard bounces, complaints, unsubscribes) | Sending to these addresses again damages reputation and breaks promises to recipients | Export in full and import before the first send |
| Templates | Content continuity | Convert template syntax if it differs between providers |
| Recent event history | Debugging and comparisons | Retention varies; export before you lose access |
| Domain and sender configuration | Rebuild on the new side | Keep a record of the old DNS records |
| Contact lists, if the provider stored them | Marketing continuity | Check consent records move with them |
Phase 4: DNS and authentication
- Add the new provider to your domain with the SPF include and DKIM records shown in its dashboard. Copy them exactly from the dashboard rather than from an article.
- Keep the old provider's records in place during the transition.
- Watch the SPF limit of ten DNS lookups; adding an include can push you over. See SPF lookup limits.
- Check DMARC alignment for both providers. See multiple vendors on one domain.
- Set up a custom return-path or tracking domain if the provider offers one, so links and bounces use your domain.
- Verify with the SPF, DKIM and DMARC checker and by sending to your own test mailboxes.
Phase 5: code changes
- Isolate the provider call. If sending code is scattered, first refactor it behind one function so you change one place. Keep a feature flag so you can switch streams between providers without redeploying.
- Switch authentication. New keys or SMTP credentials; store them in your secret manager. If you use SMTP, our relay is
smtp.migosmtp.comon port 587 with STARTTLS; see which port to use. - Map request fields. Sender, recipients, subject, text and HTML, headers, attachments, categories and custom data often have different names.
- Map templates and variables if you use stored templates.
- Update error handling. Response codes and retry guidance differ. See SMTP bounce codes explained.
- Update webhooks. Event names, payload shapes and signature verification vary. Write a translation layer so the rest of your app sees one event format.
Phase 6: test
- Send to test mailboxes at the major providers and read the authentication results in the headers. See reading email headers.
- Test failure paths: invalid address, rate limit, bad key, large attachment.
- Fire test webhook events and confirm your database updates, including bounce suppression.
- Test unsubscribe and reply handling.
- Check rendering of templates in common clients.
Use a staging environment where possible. See testing email in staging.
Phase 7: gradual cutover
| Stage | What to move | What to watch |
|---|---|---|
| 1 | Internal and low-risk mail | Authentication, rendering, webhooks |
| 2 | A small share of one real stream | Bounces, complaints, latency |
| 3 | Increasing shares over days or weeks | Provider-level delivery and Postmaster reputation |
| 4 | Full stream, then the next stream | All metrics against your baseline |
If you use new IP addresses, follow a warm-up plan rather than moving all volume at once. See the warm-up guide and dedicated vs shared IPs. Move transactional mail, which is time-sensitive, only after the new path is proven; consider moving marketing first if its schedule is flexible. Keep the streams separate. See separating the streams.
Phase 8: decommission
- Confirm nothing is still sending through the old provider by checking its logs for several days.
- Remove the old SPF include and DKIM selectors from DNS after that period.
- Revoke old API keys and SMTP credentials.
- Remove old webhook endpoints.
- Archive exports and logs for your retention period.
- Cancel the old account only when you are sure nothing depends on it.
Rollback plan
Define in advance what would make you pause: a spike in bounces or complaints, delays or webhook failures. Keep your feature flag and the old credentials working so you can send the affected stream through the old path while you investigate. Practise the rollback once during testing.
Common mistakes
- Forgetting to migrate the suppression list.
- Removing old DNS records too early, which breaks mail still sent through the old provider.
- Exceeding the SPF lookup limit.
- Not mapping webhook events, so bounces stop updating your database.
- Moving everything on one day to a cold IP.
- Changing content and infrastructure at once and being unable to tell which caused a problem.
- Skipping a baseline, so there is nothing to compare against.
Our SendGrid migration page has details for that route, and the API reference describes our endpoints.
Plan your move with us Read the migration guide or start with a small stream on the SMTP relay while your current provider keeps running.
References and further reading
Frequently asked questions
What is the most important thing to migrate?
Your suppression lists of hard bounces, complaints and unsubscribes. Sending to those addresses again damages reputation and breaks promises to recipients.
Should I move all traffic at once?
No. Move low-risk mail first, then increase shares gradually while watching bounces, complaints and provider-level delivery. New IPs also need a warm-up plan.
Can I keep both providers in my SPF record?
Yes, during the transition, but watch the limit of ten DNS lookups. Remove the old include only when nothing sends through the old provider.
What breaks most often in a migration?
Webhooks that stop updating your database, SPF records over the lookup limit, missed senders in forgotten scripts and unmapped template variables.
How do I roll back if something goes wrong?
Use a feature flag to send the affected stream through the old path, keep old credentials working until the cutover is proven and practise the rollback in testing.