Sign inGet Started

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 message-ID met em_-voorvoegsel. 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 en retourneert bij API-reads. Webhook-events kunnen deze context ook bevatten, maar uitschrijf-events kunnen null-waarden retourneren. 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. Als je het categoriebewuste gedrag voor specifieke adressen nodig hebt, bekijk dan de reason-taxonomie in Suppressions.

Voortaan maken harde bounces werkruimtesuppressies aan en sturen ze email_suppression.created, ongeacht de Brand-toewijzing. Klachten zonder betrouwbare Brand-toewijzing maken ook werkruimtesuppressies aan en sturen email_suppression.created. Klachten die aan een Brand zijn toegewezen, worden vastgelegd als beschermde voorkeuren. Uitschrijvingen worden vastgelegd als voorkeuren. Abonneer je ook op voorkeur-events, zelfs voor een werkruimte met één Brand, zodat je systeem deze opt-outs en latere toestemmingen spiegelt. De events email.complained, email.unsubscribed en email.list_unsubscribed op berichtniveau blijven beschikbaar. Zie Email events voor het onderscheid.

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.

Correleer uitgaande bericht-events met email_id en workspace_id; levenscyclus-events van ontvangers bevatten ook recipient_id. Sla die koppeling tussen bericht en klant op wanneer je verzendt. Behandel tags en metadata als extra context wanneer ze aanwezig zijn: email.unsubscribed en email.list_unsubscribed uit Bird-uitschrijflinks retourneren null-waarden voor individuele verzendingen, zelfs als de verzending ze bevatte. Uitschrijf-events van broadcasts kunnen ook null retourneren als die context niet beschikbaar is.

Gebruik preference.revoked, preference.granted en preference.deleted als signalen om je voorkeurspiegel te verversen. Deze events identificeren preference_id en transition_id, met kanaal, handle, Brand, afzender en onderwerp als bereik; ze bevatten geen message-ID's of send-metadata. Hun timestamp is het tijdstip waarop de verklaring ingaat, geen recordversie. Een vertraagde klacht kan een latere bulktoestemming intrekken, en verschillende wijzigingen kunnen dezelfde tijdstempel hebben. Bepaal de huidige status of dekking niet door events te sorteren of transition_id als volgnummer te gebruiken.

Bouw een volledige voorkeurspiegel op en onderhoud die in deze volgorde:

  1. Abonneer je op voorkeur-events en bewaar binnenkomende meldingen duurzaam voordat je met de eerste read begint.
  2. Vul de spiegel met alle pagina's van de voorkeurenlijst van de werkruimte, zonder filters op kanaal, handle of Brand. Zo ontdek je bestaande opt-outs die nooit een melding naar je endpoint hebben gestuurd. Bewaar van elk record het ID, het kanaal, de handle, de Brand, de afzender en het onderwerp als bereik.
  3. Verwerk bewaarde en nieuwe meldingen door de huidige voorkeur op te halen en alle pagina's voor het betreffende kanaal en de betreffende handle op te vragen. Vergelijk de bereiken om verwijdering en heraanmaak onder een ander ID te herkennen. Stem daarnaast periodiek af met de volledige, ongefilterde lijst van de werkruimte, inclusief ontvangers die niet in meldingen of in je lokale spiegel voorkomen.

Reads kunnen achterlopen op een wijziging: probeer het opnieuw bij tijdelijke fouten en bij onverwacht ontbrekende of oudere status. Een mislukte of onvolledige read mag een lokale blokkade niet wissen. Verwijder een verwijderd record pas nadat je hebt bevestigd dat het ontbreekt; laat onafhankelijke voorkeuren en suppressies staan. Deze spiegel convergeert na verloop van tijd en vervangt de controles van Bird bij het verzenden niet.

email_suppression.created identificeert toevoegingen via suppression_id, workspace_id en email. Er is geen event voor het verwijderen van suppressies door klanten. Om verwijderingen in het dashboard of via API te ontdekken, lees je periodiek alle pagina's van de suppressielijst van de werkruimte en stem je af op suppressie-ID. Verwijder geen records na een mislukte of gedeeltelijke scan; bevestig bij een volgende read dat records ontbreken voordat je ze verwijdert. Houd suppressierecords gescheiden van voorkeuren, zodat het verwijderen van de ene blokkade geen andere kan wissen.

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 schema voor opnieuw proberen en de replay-tooling in Webhooks & events. Leveringen gebeuren minstens één keer en zonder vaste volgorde, dus dedupliceer op webhook-id. Gebruik de tijdstempels van bericht-events om de chronologie van berichten te tonen; gebruik afstemming op de huidige status voor voorkeuren en suppressies, zoals hierboven beschreven.

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

Test de geporte send-aanroep en de handler voor bericht-events tegen de mail-sandbox voordat je productieverkeer verplaatst. 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.

Sandboxsignalen schrijven geen suppressierecords of klachtvoorkeurrecords. Test je spiegel apart met representatieve email_suppression.created-, preference.revoked-, preference.granted- en preference.deleted-payloads uit de webhook-eventcontracten, inclusief twee Brands met dezelfde ontvanger. Neem deze gevallen op:

  • Een ongewijzigde opt-out bestaat al vóór de registratie van de webhook. De eerste ongefilterde inventarisatie ontdekt deze zonder melding; periodieke inventarisatie ontdekt ook een record dat in je lokale spiegel ontbreekt.
  • Een uitschrijving bij een individuele verzending heeft null voor tags en metadata; je opgeslagen berichtkoppeling identificeert de klant nog steeds.
  • Een klacht komt binnen na een nieuwere bulktoestemming, of een oudere opt-out voor alle categorieën verbreedt de klachtbescherming zonder de ingangstijdstempel te verschuiven. Lever de events in omgekeerde volgorde en controleer dat de afstemming de huidige ingetrokken status en dekking behoudt.
  • Een voorkeur wordt verwijderd en opnieuw aangemaakt, of een handmatige suppressie wordt in het dashboard verwijderd. De afstemming verwijdert alleen records waarvan bevestigd is dat ze ontbreken en behoudt niet-gerelateerde blokkades.
  • Een verversing mislukt of retourneert tijdelijk een oudere status. Je handler probeert het opnieuw en periodieke afstemming herstelt de spiegel zonder blokkades te wissen bij de mislukte read.

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

  • SparkPost: transmissions en SMTP, templateconversie, scoped suppressies en webhook-events
  • 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

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.