How to switch Email Providers without risking Deliverability

Picture the migration that keeps engineers up at night. You flip the switch on Friday afternoon, point every transactional email at the shiny new provider, and go home. By Monday, support is on fire: password resets are landing in spam, receipts never arrived, and a chunk of your login codes bounced. Nobody changed the email content. You just moved providers, all at once, and your users paid for it.

It does not have to go like that. Your team already has a playbook for shipping risky changes safely, and it is called the canary deploy. You roll the change out to a sliver of traffic, watch the dashboards, and expand only when the numbers hold. The same idea works beautifully for email. Send a tiny fraction of your messages through the new provider, measure deliverability against your current baseline, and turn the dial up one notch at a time. By the time you hit 100%, the cutover is a non-event, which is the highest compliment you can pay a migration.

This guide walks through that approach end to end, using AhaSend as the destination, and covers both the HTTP API and SMTP.

TL;DR: Do not big-bang your email migration. Put a weighted router in front of your providers, controlled by a single number. Start at 5% to AhaSend, watch delivery, bounce, and complaint rates against your old provider, and ramp to 100% over a couple of weeks. Both providers stay live the whole time, so rollback is instant.

Why the big-bang cutover is so risky

Three forces conspire to make an overnight switch dangerous, and all three are invisible until real traffic arrives.

Reputation does not transfer. Mailbox providers like Gmail and Outlook judge a sending domain and IP by their recent history, and a brand new setup has none. A sudden flood of mail from an unknown source looks suspicious, so even perfectly legitimate messages can slide straight into spam. Depending on your volume, this is also a warm-up problem. High-volume senders normally introduce a new IP or domain gradually over days or weeks so that reputation builds in step with volume. An overnight switch skips that warm-up completely, and your mail gets throttled or bounced until reputation catches up. A gradual migration is, conveniently, a warm-up in disguise.

Configuration bugs stay hidden until volume finds them. An SPF record that is almost right, a DKIM key that signs some messages but not others, a suppression list that quietly failed to migrate: none of these surface when you send yourself a test email, and all of them surface at scale. AhaSend removes one entire category of this pain. You cannot send through a domain whose DNS is not correctly configured, because we verify it continuously, all day long. A broken domain fails fast and loud instead of silently eroding your inbox placement for a week.

You lose your safety net. With one provider and one switch, your rollback plan is another emergency deploy, under pressure, while the incident is live. Weighted splitting keeps both providers running side by side, so backing out is a config change you make in seconds, not a fire drill.

The core idea: a canary deploy for email

Put a small router between your application and your email providers. For every message, it makes one decision against a percentage you control: does this one go to AhaSend, or stay on your current provider? Set the dial to 5% and about one message in twenty flows through AhaSend while the rest follow the old path. Watch the metrics, and when AhaSend's numbers look healthy, open the dial wider.

A sensible ramp looks like this:

The exact percentages matter less than the discipline behind them: change one thing at a time, give each stage long enough to expose problems, and advance only when the data is clean.

Before you start

The canary only tells you the truth if the foundation is solid, so get these three things in place first.

Authenticate your domain on AhaSend, the same sending domain you use today. Add the SPF, DKIM, and DMARC records AhaSend provides, then verify the domain in the dashboard. A single domain can authenticate mail through more than one provider at the same time, and that overlap is exactly what makes a gradual migration possible. The domain setup guide has the records.

Create your sending credentials. For the HTTP API, generate an API v2 key as described in the API keys guide. For SMTP, create SMTP credentials following the SMTP credentials guide.

Decide how you will measure success before you send a single canary message. You want delivery rate, bounce rate, and complaint rate per provider, sitting side by side. AhaSend gives you deliverability reports, bounce reports, and real-time webhooks for delivery, bounce, and complaint events. Pull the matching numbers from your current provider so you are always comparing like with like.

One optional extra, and it really is optional: if you want to slice your migration traffic out from everything else later, tag your AhaSend sends with the ahasend-tags header (something like migration,canary) and filter on it in your logs and reports. Skip it without a second thought if you would rather keep things lean. It has zero effect on deliverability, it is purely a convenience for your own reporting.

Step 1: Decide how traffic gets split

The heart of this approach is a small piece of routing logic that lives between your application and your email providers. Every time your app sends a message, this logic makes exactly one call: AhaSend, or the current provider?

That call is driven by a single number, the share of traffic you want on AhaSend, stored somewhere you can change without shipping code, such as an environment variable or a feature flag. For each message, the logic compares that number against a random draw. Set the share to 5 and roughly one message in twenty is routed to AhaSend while the rest stay put. Moving the dial means changing one value and nothing else, and that single property is what makes every later step safe and reversible.

In code, the whole decision is just a few lines:

import os
import random

# Share of traffic sent to AhaSend, 0 to 100. Change it without a deploy.
AHASEND_WEIGHT = float(os.environ["AHASEND_WEIGHT"])

def pick_provider():
    return "ahasend" if random.uniform(0, 100) < AHASEND_WEIGHT else "legacy"

There is one refinement worth knowing. Deciding per message is perfectly fine for most transactional mail, but if you would rather keep a given user on the same provider throughout the migration (handy for clean per-user comparisons), base the decision on a stable key such as the user ID instead of a fresh random draw. Hash the key, map it to a value between 0 and 100, and compare that to your threshold. The same user then lands on the same provider every time until you decide to move the dial.

Everything downstream, the metrics you watch and the ramp you follow, depends on nothing more than this one number staying easy to change.

Step 2: Send through AhaSend

There are two ways to actually hand a message to AhaSend. Most teams choose one based on what their stack already speaks, and the router from Step 1 simply calls the matching path whenever it picks AhaSend.

Option A: the HTTP API

AhaSend's API v2 exposes a single create-message endpoint:

POST https://api.ahasend.com/v2/accounts/{account_id}/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

The Send emails using the API guide walks through the full JSON body, the response shape, and the options that matter most during a migration, including idempotency keys for safe retries, batching up to 100 recipients per request, and per-message retention control, all with copy-paste examples.

Option B: SMTP

If your application already speaks SMTP, you can route to AhaSend just by swapping the host and credentials, with no change to how you build the message itself. AhaSend's SMTP relay uses these settings:

Host: send.ahasend.com
Ports: 25, 587, or 2525
Encryption: STARTTLS (required)
Authentication: PLAIN

Your routing logic simply chooses which provider's SMTP host and credentials to use for each message. The SMTP server guide covers credentials, connection limits, the special headers you can set per message, and ready-to-use examples for every major language.

Step 3: Watch the right metrics

A canary is only as good as the dials you read. At every stage, compare these numbers between AhaSend and your current provider over the same window.

Delivery rate is the headline. It is the share of accepted messages that actually reached the inbox provider, and a healthy migration shows AhaSend tracking your current provider within a point or two. A stubborn gap means something in your setup wants attention before you ramp.

Bounce rate, split into hard and soft, reveals list quality and configuration problems. Hard bounces that appear only on AhaSend traffic usually point to a domain or authentication issue rather than bad addresses, because the very same recipients are succeeding on the other provider. Read these from the bounce report.

Complaint rate is your hard stop. If recipients mark AhaSend mail as spam at a higher rate than your baseline, pause the ramp and dig into content, authentication, and list hygiene before you go a step further.

Deferrals and delivery time complete the picture. A brief rise in deferrals during a fresh ramp can be normal as reputation builds, but a sustained climb is a warning sign. AhaSend's delivery time statistics show how quickly mail is actually landing.

Wire up webhooks for delivered, bounced, and complaint events so problems reach you in minutes rather than at the end of the day. And if you tagged your migration traffic with ahasend-tags, you can isolate exactly the canary slice in your own dashboards.

Step 4: Ramp, gate, and roll back

Advancing is nothing more than editing the share value and redeploying the config, or flipping a feature flag if you wired one up. Keep one rule sacred: never change the percentage, a message template, and your domain records in the same move. One variable at a time keeps cause and effect legible when you are reading the metrics.

Before each increase, confirm the gate for the current stage. Delivery rate in line with the old provider, bounces in their normal range, complaints low, and deferrals stable across a representative window that includes your busy periods. If a gate fails, hold or step back rather than push through and hope.

Rolling back is the easy part, and that ease is the entire point of this approach. Set the share to 0 and every message flows to your current provider again, with no emergency deploy and no 2am scramble. Investigate calmly, fix the issue, and resume the ramp when you are ready.

Step 5: Finish the job

Once you have run a quiet week at 100%, close it out properly. Make sure suppression handling lives entirely on AhaSend so you never re-mail an address that bounced or complained. AhaSend manages suppressions automatically, and you can import known-bad addresses from your old provider so those hard-won reputation lessons carry over. Then pull the old provider's credentials, retire the legacy branch of your router, and leave the weighted router in place. The next time you need to test a configuration change, the dial is already there waiting.

The takeaway

Migrating transactional email does not have to be a leap of faith, and it definitely should not be a Friday-afternoon gamble. Treat it like a canary deploy: route a small share of traffic to the new provider, watch delivery, bounces, and complaints against your current baseline, and increase the share only when the data earns it. With a weighted router controlled by a single config value, both providers stay live the whole time, rollback is instant, and the final cutover is the quietest deploy you will ship all quarter.

AhaSend is built for exactly this kind of careful, developer-led migration: a clean API v2 and SMTP relay, continuous DNS verification so a misconfigured domain can never quietly hurt you, optional per-message tagging and retention control, real-time webhooks, and the deliverability and bounce reports you read your canary by. The free tier gives you 1,000 emails a month to route your first 5% through. Start for free on AhaSend →