Het draaiboek voor het migreren van transactionele e-mail

De kernuitdaging van een migratie

Om transactionele e-mail te migreren zonder observability te verliezen, moet je de verzendtrigger loskoppelen van de implementatie van de provider. De strategie is een abstractielaag voor providers die dual-sending (shadowing) en eventmapping mogelijk maakt. Door een klein percentage van het verkeer naar de nieuwe provider te routeren en tegelijk bezorgevents via webhooks te blijven volgen, kun je verifiëren dat de nieuwe provider de e-mail accepteert en dat je observabilitypipeline de resultaten vastlegt, voordat je de hoofdstroom omzet.

Waarom migraties plaatsvinden

De meeste migraties worden gedreven door kosten, developer experience of compliance. Het kostenverschil tussen providers is bijvoorbeeld aanzienlijk. Volgens de prijzen van Amazon SES kost verzenden a la carte 0.10 USD per 1.000 e-mails. De prijzen van Postmark beginnen daarentegen bij 15 USD per maand voor 10.000 e-mails, met overschrijdingen tussen 1.80 en 1.20 USD per 1.000. 50.000 e-mails versturen kost ongeveer 5 USD bij SES a la carte, tegenover ongeveer 66 USD bij de niveaus van Postmark.

Andere redenen zijn de verschuiving naar privacyvriendelijke telemetrie uitsluitend in de EU of de behoefte aan betere agentgereedheid (zoals ondersteuning voor MCP-servers). Wat de reden ook is, het risico is hetzelfde: een blinde vlek in je bezorgpipeline tijdens de overgang.

Fase 1: de abstractielaag

Roept je applicatie de SDK van een provider direct aan vanuit je bedrijfslogica, dan zit je vast. Je hebt een wrapper nodig die de request en de respons standaardiseert.

De uniforme payload

Definieer een intern schema dat onafhankelijk is van de provider. Zo maakt het je applicatie niet uit of de onderliggende API to verwacht als array of als losse string.

{ "message_id": "msg_12345", "recipient": "user@example.com", "template_id": "welcome_email", "variables": { "name": "Alex" }, "idempotency_key": "unique_request_id_789" }

Bij AI-agents of geautomatiseerde workflows is het essentieel om e-mail als een extern neveneffect te behandelen. Gebruik een idempotentiesleutel om te voorkomen dat een agentlus die opnieuw wordt uitgevoerd dezelfde transactionele e-mail vijf keer naar één gebruiker stuurt.

Fase 2: DNS en identiteit instellen

Voordat je ook maar één e-mail verstuurt, moet je je identiteit vastleggen. Hier lopen de meeste migraties spaak door vertraging in de DNS-propagatie of verkeerde configuraties.

1. Domeinen verifiëren: voeg de DKIM- en SPF-records van de nieuwe provider toe. Gebruik een tool zoals de E-mail-DNS-checker van SendHQ om te controleren of je records live staan en correct zijn opgemaakt.
2. De records begrijpen: zorg dat je het verschil begrijpt tussen SPF (dat de server autoriseert) en DKIM (dat het bericht ondertekent). Gebruik je tijdens een migratie meerdere providers, dan moet je SPF-record ze allebei bevatten.
3. DMARC-alignment: zet je DMARC-beleid tijdens de eerste migratiefase op p=none, zodat je geen hard bounces krijgt als de alignment net niet klopt. Zie de gids van SendHQ over DKIM, SPF en DMARC voor gedetailleerde stappen.

Fase 3: de shadow send (dual-sending)

Zet niet in één keer een schakelaar om. Implementeer in plaats daarvan routeringslogica die naar de primaire provider verstuurt en asynchroon een duplicaat (of een steekproefpercentage) naar de nieuwe provider stuurt.

Implementatielogica

async function sendEmail(payload) { // Primary send (Current Provider) const primaryResult = await primaryProvider.send(payload); // Shadow send (New Provider) - do not await or block the main thread if (Math.random() < 0.1) { // 10% sample newProvider.send(payload).catch(err => console.error("Shadow send failed", err) ); } return primaryResult; }

In deze fase test je acceptatie door de provider. Dat is het moment waarop de provider zegt: "Ja, ik neem dit bericht aan." Dat is iets anders dan bezorging (het bericht bereikt de ontvangende server) en inboxplaatsing (het bericht ontloopt de spammap).

Fase 4: observability en gelijkwaardige events

Observability is het vermogen om een bericht te volgen van sent tot delivered of bounced. Elke provider heeft een ander webhookschema.

De events koppelen

Maak een koppeltabel om events te normaliseren in je interne database:

Intern event | Amazon SES | Resend | Postmark | SendHQ

sent | Send | sent | Sent | sent

delivered | Delivery | delivered | Delivered | delivered

bounced | Bounce | bounced | Bounced | bounced

complaint | Complaint | complained | Complaint | complaint

Webhookpayloads afhandelen

Je webhooklistener hoort generiek te zijn. Ontvang je een payload van een nieuwe provider, dan moet die eerst door een transformer voordat hij je analytics-engine bereikt.

function transformWebhook(provider, payload) { switch(provider) { case 'resend': return { event: payload.data.delivered ? 'delivered' : 'failed', id: payload.data.id }; case 'sendhq': return { event: payload.event, id: payload.message_id }; default: throw new Error("Unknown provider"); } }

Fase 5: de geleidelijke overgang

Heb je geverifieerd dat de nieuwe provider de e-mail accepteert en dat je webhooks de events correct koppelen, stap dan over op een gewogen verdeling.

1. 1% van het verkeer: routeer 1% van alle transactionele e-mail naar de nieuwe provider. Houd het bouncepercentage in de gaten.
2. 10% van het verkeer: verhoog de belasting. Controleer op rate limits. Het gratis niveau van Resend is bijvoorbeeld beperkt tot 100 e-mails per dag, wat tijdens het testen een knelpunt kan zijn.
3. 50% van het verkeer: dit is de stabiliteitstest. Zorg dat je latency acceptabel blijft.
4. 100% van het verkeer: de definitieve overstap.

Veelvoorkomende migratiefouten oplossen

De "stille drop"

Sommige providers accepteren de e-mail (202 Accepted) maar laten hem intern vallen door contentfilters of niet-geverifieerde afzenderidentiteiten. Daarom is de shadow-sendfase niet onderhandelbaar. Zijn je sent-events hoog maar je delivered-events laag, dan heb je een bezorgprobleem, geen API-probleem.

Pieken in rate limits

Verschillende providers hebben verschillende burstlimieten. De prijzen van Mailgun en de prijzen van SendGrid (dat voor het gratis niveau nu een proefperiode van 60 dagen gebruikt) gaan vaak gepaard met verschillende doorvoerquota. Migreer je van een account met hoge limieten naar een nieuw account, dan kun je worden afgeknepen. Implementeer een queue (zoals RabbitMQ of SQS) om pieken op te vangen.

Fouten in idempotentie

Bij het wisselen van provider kun je per ongeluk een retry van een batch activeren. Gebruik je AI-agents om e-mails te versturen, zorg dan dat de agent een uniek request-ID meegeeft. Gebruikt de agent een MCP-server om met je e-mail-API te werken, dan hoort de API dubbele idempotency_key-waarden binnen een venster van 24 uur te weigeren.

Migratiechecklist

• Abstractielaag geïmplementeerd (provider-agnostische payload).
• DNS-records (SPF, DKIM) toegevoegd voor de nieuwe provider.
• DNS geverifieerd via sendhq.cc/tools/email-dns-checker.
• Webhooklistener bijgewerkt om schema's van de nieuwe provider af te handelen.
• Tabel voor eventmapping voltooid (Sent, Delivered, Bounced, Complaint).
• Shadow sending actief op 1% tot 10%.
• Idempotentiesleutels geverifieerd voor door agents aangestuurde verzendingen.
• Geleidelijke opschaling (1%, 10%, 50%, 100%).
• API-sleutels van de oude provider ingetrokken na 7 dagen van 100% stabiliteit.

Tot slot: de keuze van een provider

Het kiezen van een provider is een afweging tussen kosten en ontwikkelsnelheid. Heb je de allerlaagste kosten nodig, dan is Amazon SES moeilijk te verslaan met 0.10 USD per 1.000 e-mails a la carte, al brengen de nieuwe abonnementsniveaus (Essentials voor 0.16 USD, Pro voor 0.22 USD) sinds 21 juli 2026 andere kostenstructuren met zich mee. Heb je een moderne API nodig met ingebouwde agentgereedheid en privacyvriendelijke telemetrie uitsluitend in de EU, dan biedt SendHQ een gestroomlijnd alternatief.

Ongeacht de provider is het doel dat je engineeringteam niet vastzit aan de SDK van een specifieke leverancier. Door e-mail te behandelen als een gestandaardiseerd neveneffect maak je van een risicovolle migratie een routinematige configuratiewijziging.

Lees meer over het bouwen van betrouwbare e-mailworkflows op https://sendhq.cc.