Documentatie
Sign inGet started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

Migreren van een andere provider

Gebruik deze handleiding om productie-e-mail van een andere provider te verplaatsen. Vertaal het send-request, publiceer DNS-records, importeer suppressies, vertaal webhook-events en test de integratie voordat je productieverkeer naar Bird stuurt.
De migratiechecklist:
  1. Vertaal je send-aanroep naar POST /v1/email/messages
  2. Wijs je verzenddomeinen en DNS opnieuw aan
  3. Importeer je suppressielijst
  4. Schakel webhooks over naar ons event-vocabulaire
  5. Verifieer tegen de mail-sandbox vóór de cutover
Stap 1, 3 en 4 hangen af van welke provider je verlaat. Je providergids bevat de veld-voor-veld payload-mapping, waar je je suppressielijst exporteert, en de vertaaltabel voor webhook-eventnamen.

1. Vertaal de send-aanroep

We hebben één single-send endpoint, POST /v1/email/messages. Je bouwt een platte JSON-payload (geen personalizations-wrapper, geen MIME-opbouw) met from, to/cc/bcc-arrays, subject, html en/of text, een optionele reply_to-lijst, en headers voor aangepaste e-mailheaders. Een succesvolle send retourneert 202 Accepted met een em_-voorvoegsel als message-ID. Afleverresultaten komen asynchroon binnen via webhooks en de read-endpoints. De volledige payload, met elke veldlimiet en standaardwaarde, staat in E-mail verzenden. De veld-voor-veld mapping vanuit je huidige payload staat in je providergids. Als je applicatie vandaag via SMTP verstuurt, hoef je de aanroep mogelijk helemaal niet te porten: we accepteren SMTP-indiening in dezelfde pipeline, waardoor deze stap een credentials-wissel wordt.
Gebruik tags voor filterdimensies in berichtlijsten, analytics en dashboard-rollups. Gebruik metadata voor gestructureerde context die Bird op het bericht opslaat, retourneert bij API-reads en meestuurt bij webhook-events. Zie Tags vs metadata voor limieten.
Houd rekening met deze verschillen voordat je code port:
  • Planning, opgeslagen templates en bijlagen zijn allemaal porteerbaar. Gebruik scheduled_at voor geplande verzending. Gebruik template in plaats van inline content voor opgeslagen templates. Map bestanden naar de attachments-array.
  • Onderdrukte ontvangers worden zichtbaar geweigerd. Een onderdrukt adres krijgt nog steeds een recipient_id en verschijnt in de ontvangerslijst van het bericht met status rejected en een email.rejected-event (rejection_reason: recipient_suppressed), nooit een stille drop. Zelfs als elke ontvanger onderdrukt is, wordt het request gewoon geaccepteerd met een 202. Elke ontvanger komt geweigerd terug. Zie Suppressions.
  • Stel category: "transactional" in voor operationele mail. Een send staat standaard op marketing en de categorie bepaalt het suppressiebeleid: marketing blokkeert bij klachten en uitschrijvingen, transactional levert er doorheen. Nieuwsbrieven en campagnes worden correct afgehandeld door de standaardinstelling. Markeer bonnetjes, wachtwoordresets en vergelijkbare operationele mail als transactional, zodat ze niet worden geblokkeerd door een uitschrijving.

2. Domeinen en DNS opnieuw aanwijzen

Registreer elk verzenddomein met POST /v1/email/domains of in Email > Domains, en publiceer vervolgens de records uit dns_records. DKIM, de return-path CNAME en een DMARC-beleid zijn vereist voor verzending. Een bestaand DMARC-record, ook op een bovenliggend domein, telt mee. De tracking-CNAME is alleen vereist voor branded open- en click-tracking. Verzenddomeinen behandelt de records, de verificatielevenscyclus en het regionale model. Gebruik de DNS-record splitter als je provider een gesplitste DKIM-waarde vereist, en de DMARC-beleidsgenerator als je een beleid nodig hebt.
Eén record waarmee de meeste providers je laten beginnen, ontbreekt bewust: je publiceert geen SPF-record op je domein-apex. SPF wordt geëvalueerd tegen het envelope-from-domein, dat de return-path CNAME naar ons verwijst, dus SPF slaagt en aligneert zonder je apex aan te raken. Als je oude provider je een include: heeft laten toevoegen aan je apex SPF-record, laat het dan staan tijdens de transitie en verwijder het na de cutover. Het helpt noch schaadt mail die via ons wordt verzonden, en het verwijderen maakt één van de 10 DNS-lookups vrij die apex SPF toestaat. De volledige uitleg staat in DKIM, SPF & DMARC.
Je kunt onze records publiceren terwijl de records van je oude provider nog actief zijn. Het DKIM-record gebruikt een selector van ons. De return-path- en tracking-CNAMEs zijn nieuwe hostnames die je zelf kiest, en je bestaande DMARC-record voldoet aan de vereiste zoals het is. Beide providers authenticeren naast elkaar totdat je klaar bent om het verkeer over te schakelen. Domeinstatus is regionaal, dus registreer het domein in elke regio van waaruit je verzendt.

3. Suppressies importeren

Neem je suppressielijst over vóórdat je productieverkeer via ons verzendt. Anders gaan je eerste verzendingen naar adressen die al zijn gebounced of waartegen al klachten zijn ingediend bij je oude provider, wat de reputatie schaadt die je probeert te beschermen.
Exporteer de lijst van je huidige provider (je providergids heeft de exacte endpoints) en voeg elk adres hier toe met POST /v1/email/suppressions:
Codevoorbeeld
while read -r address; do
  curl -s -X POST https://us1.platform.bird.com/v1/email/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$address\"}"
done < suppressions.txt
Twee dingen om te weten over dit importpad:
  • Je importeert één adres per request. De suppressies-API is single-entry CRUD, dus een grote lijst betekent loopen over de geëxporteerde adressen. De aanroep is idempotent (201 voor een nieuw record, 200 met het bestaande record als het adres al handmatig onderdrukt is), dus het opnieuw uitvoeren van een gedeeltelijke import is veilig.
  • Geïmporteerde adressen krijgen reason: manual, applies_to: all, wat elke categorie blokkeert, inclusief transactioneel. Dat is strenger dan een native klachtrecord, dat alleen niet-transactionele verzendingen blokkeert, dus als je het categoriebewuste gedrag voor specifieke adressen nodig hebt, bekijk dan de reason-taxonomie in Suppressions.
Voortaan beheer je bounces niet meer zelf: wij onderdrukken hard bounces en klachten automatisch en vuren email_suppression.created zodat je systemen de suppressielijst kunnen spiegelen. Uitschrijvingen worden in plaats daarvan vastgelegd als een geuite voorkeur en gespiegeld via email.unsubscribed en email.list_unsubscribed, niet via het suppressie-event.

4. Webhooks overschakelen

Registreer een endpoint met POST /v1/webhooks en abonneer het op een expliciete lijst van event-typen. Onze eventnamen volgen resource.action: email.accepted → email.processed → email.delivered op het succespad, met email.deferred, email.bounced, email.complained, email.rejected, email.opened, email.clicked en het uitschrijfpaar voor de rest. De eventnaam-vertaling vanuit het vocabulaire van je huidige provider staat in je providergids. Per-event payload-schema's staan in de events reference.
Correlatie port soepel mee. Elk event bevat de email_id-, recipient_id- en workspace_id-identifiers. Het echoot ook de tags en metadata uit het send-request. Dit geeft de context terug die je oude provider via payload-echo meegaf, zonder een extra lookup. Zet je interne ID's in metadata bij de send en lees ze direct uit elk event.
We ondertekenen leveringen volgens de Standard Webhooks-specificatie, met drie headers: webhook-id, webhook-timestamp en webhook-signature, met een HMAC-SHA256 over {id}.{timestamp}.{raw body}. Als je al Standard Webhooks-leveringen van een ander platform verifieert, werkt exact dezelfde verificatiecode hier. Anders staan het verificatierecept, het retry-schema en de replay-tooling in Webhooks & events. Leveringen zijn at-least-once en ongeordend, dus dedupliceer op webhook-id en sorteer op de payload timestamp, dezelfde discipline die je huidige handler al zou moeten hebben.

5. Verifieer in de sandbox vóór de cutover

Voordat je productieverkeer verplaatst, voer je je volledige integratie uit (de geporte send-aanroep, je webhook-handler, je suppressiespiegeling) tegen de mail-sandbox. Sandbox-sends gaan naar magic-adressen op messagebird.dev en doorlopen de echte productiepipeline: dezelfde 202, dezelfde eventsequentie, dezelfde ondertekende webhook-leveringen, zonder ooit een inbox te bereiken of je reputatie aan te raken.
Een minimale pre-cutover smoke test:
  1. Verstuur naar delivered@messagebird.dev en controleer dat je handler email.accepted → email.processed → email.delivered verwerkt.
  2. Verstuur naar bounce@messagebird.dev en controleer dat je bounce-handling triggert op email.bounced (gesimuleerde bounces schrijven niet naar je suppressielijst, dus het adres blijft herbruikbaar).
  3. Verstuur naar suppressed@messagebird.dev en controleer dat je email.accepted gevolgd door email.rejected afhandelt, zonder email.processed of delivery-events daarna. Dat is de vorm die elke onderdrukte ontvanger in productie oplevert; het rejection_reason: recipient_suppressed-detail staat op het ontvangersrecord en de events API.
  4. Verstuur een category: "marketing"-bericht en controleer of de categorie verschijnt waar je verwacht bij het lezen van het bericht.
Gebruik +label-subaddressing (bounce+cutover-test@messagebird.dev) om testcases te correleren. Het volledige adres verschijnt in je events. Als de smoke test slaagt, schakel je het verkeer over. Wijs je applicatie naar ons en laat de DNS van je oude provider staan totdat je domeinen hier capabilities.sending verified tonen. Houd de eerste uren van echte leveringen in de gaten in het dashboard en je webhook-stream.

Migreren van een specifieke provider

  • SendGrid: personalizations → platte payload, categories/custom_args → tags/metadata, de dropped ↔ email.rejected-equivalentie
  • Mailgun: o:*/v:*/h:*-parameters → first-class velden, bounces/complaints/unsubscribes-export
  • Amazon SES: SendEmail v2 → één endpoint, configuration sets → per-bericht tracking-flags, SNS → ondertekende webhooks
  • Resend: bijna identieke payload-structuur, Svix-ondertekende webhooks → Standard Webhooks
  • Postmark: kommagescheiden ontvangers → arrays, per-stream suppressie-dumps, niet-ondertekende webhooks → ondertekend
  • Brevo: adresobjecten → platte adressen, twee aparte blocklists om te exporteren, params → template.parameters
  • MailerSend: vijf suppressielijsten waarvan de tijdelijke achterblijft, personalization → per-send parameters
  • Mailjet: de Messages-array → één platte payload, EventPayload → metadata, blocklist-export
  • Mandrill: de message-wrapper en body-auth → platte payload en bearer-auth, rejection-blacklist-export

Volgende stappen

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsGetting started with emailOntdek de mogelijkheidEmailVolg het leerpadBuild your first integrationImplementatiegidsSend your first email
Probeer de oefening en ontvang een implementatieoverzicht