Migreren vanaf SparkPost

Gebruik deze gids om uitgaande e-mail van SparkPost naar Bird te verplaatsen. Volg de hoofdchecklist voor migratie en gebruik de onderstaande mappings voor je HTTP- of SMTP-integratie.

Voordat je begint

Je hebt toegang nodig tot je SparkPost-account en subaccounts, DNS van je verzenddomein, applicatieconfiguratie en webhook-handler. Bereid een Bird-werkruimte en API-sleutel voor in je gekozen regio. De opt-out-import vereist ook preferences-schrijfrechten op de sleutel.

Inventariseer afzenders, templates, snippets, ontvangerslijsten, suppressies, geplande verzendingen, IP-pools en webhooks. Neem SDK's, framework-mailadapters, achtergrondtaken en inkomende e-mailstromen mee. Noteer nieuwe resource-ID's zodra je ze aanmaakt; SparkPost-ID's en -inloggegevens werken niet in Bird. Gebruik de Bird-SDK's als vervanging voor een SparkPost-client en controleer de retries, timeouts en paginering.

Als je SparkPost-subaccounts gebruikt, neem contact met ons op voordat je een werkruimte-indeling kiest. Controleer de beschikbare werkruimtes, rechten, gedeelde resources en de workflow voor tenantprovisioning. Een werkruimte-API-sleutel kan niet van tenant wisselen met X-MSYS-SUBACCOUNT. Behoud opgeschorte tenants en tenantspecifieke verzendbeperkingen tijdens de migratie.

Controleer of je Bird-plantoewijzingen en limieten voor het aantal verzoeken je verzendvolume, aantal resources en piekverkeer dekken.

Registreer je verzenddomeinen vroegtijdig. Behoud werkende SparkPost-DNS en kies waar nodig aparte return-path- en trackinghostnamen. Als de registratie een eigendomsconflict meldt, neem contact op met support voordat je een actief domein verwijdert.

Dedicated IP's: Neem contact met ons op of met je accountteam voordat je migreert. Vraag ons te bevestigen of je bestaande SparkPost-IP's naar Bird kunnen worden verplaatst en maak afspraken over poolconfiguratie, timing en eventuele opwarming. Vermeld je accountregio, IP-adressen, poolnamen en verzendvolume. Houd je huidige IP's actief totdat het migratieplan is bevestigd.

Controleer poolselectie en IP- of hostnaam-allowlists van ontvangers vóór de cutover. Het kopen van een IP wijzigt de standaardpool niet. Nieuw aangeschafte IP's kunnen overflow via gedeelde infrastructuur verzenden tijdens de opwarming, wat uitmaakt als ontvangers alleen e-mail accepteren van specifieke IP's.

Geef dit aan je agent

Plak dit in je coding-agent in je applicatie-repository:

Help me migrate my SparkPost email integration to Bird.
1. Use an existing Bird MCP connection or signed-in CLI. Otherwise follow https://bird.com/docs/ai/set-up-your-agent.md. Append .md to Bird docs URLs to read Markdown.
2. Read https://bird.com/docs/guides/email/migrate/sparkpost.md and https://bird.com/docs/guides/email/migrate.md. Make a read-only inventory of my SparkPost call sites, SDKs, resource IDs, configured URLs, sending domains, and scheduled jobs before editing. Never print API keys.
3. Propose workspace and region mappings. If subaccounts, dedicated IPs, or domain ownership conflicts need a migration plan, use the available Bird tools to open a human email support ticket and return its ID. For CLI usage, read https://bird.com/docs/cli/reference/support-tickets-create.md. Wait for the agreed plan before moving those resources.
4. Follow https://bird.com/docs/guides/email/sending-domains.md; preserve working DNS and show me proposed records. Ask before DNS changes or paid provisioning.
5. Port sending, templates, and webhooks using this guide. Preserve recipient privacy, personalization, and categories. Export suppressions with scope and type; show me the handling before importing or changing preferences.
6. Test using https://bird.com/docs/guides/email/testing-sandbox.md. Show me results and unresolved differences, including tracking, signatures, and correlation.
7. Ask for explicit approval before production cutover. Keep a rollback path; get separate approval before retiring SparkPost resources or credentials.

Vertaal de verzendaanroep

Vervang POST /api/v1/transmissions door POST /v1/email/messages, of POST /v1/email/batches voor onafhankelijke berichten. Het SparkPost API-overzicht vermeldt de regionale hosts en authenticatie. Bird gebruikt https://us1.platform.bird.com of https://eu1.platform.bird.com, overeenkomend met de regio van je API-sleutel, met Authorization: Bearer $BIRD_API_KEY.

Een SparkPost-transmissie kan afzonderlijke, gepersonaliseerde e-mails genereren voor de ontvangers. Bird deelt inhoud en parameters over de ontvangers van één verzending. Gebruik een apart bericht per personalisatie, optioneel gegroepeerd in een batch. Verzendingen met alleen To blijven individueel geadresseerd; controleer de zichtbare headers wanneer je Cc/Bcc-kopieën toevoegt.

Vertaal de SparkPost-transmissievelden:

Bouw voor To/Cc/Bcc-kopieën van één e-mail de ontvangersgroep één keer op. De weergegeven adressen van SparkPost kunnen afwijken van de afleverontvangers; to, cc en bcc van Bird voegen elk afleverontvangers toe. Een SparkPost CC-header kopiëren naar de cc van elk uitgebreid bericht kan dubbele kopieën versturen. Controleer zichtbare headers en aantallen ontvangers voordat je overschakelt.

Controleer limieten voor verzendvelden, planning en bijlageregels. Werk inline-afbeeldings-ID's en bijbehorende cid:-referenties bij zodat ze voldoen aan de regels van Bird. Configureer het return path en het trackingdomein op het domein.

De HTTP-verzendvelden van Bird bevatten niet SparkPost's content.email_rfc822, content.amp_html of options.inline_css. Bouw ruwe berichten op met de ondersteunde velden, bied HTML/text-fallbacks voor AMP, en inline CSS voordat je HTML indient. SMTP parseert en bouwt ondersteunde berichtonderdelen opnieuw op; valideer de ontvangen MIME als je afhankelijk bent van de exacte structuur. MIME-parameters van bijlagen zoals agenda method of tekst charset blijven niet behouden.

Voor geplande API-berichten legt Bird de templateversie, taal en parameters vast op het moment van acceptatie. Latere templatewijzigingen werken dat bericht niet bij. Om het te wijzigen, annuleer het geplande bericht voordat de verwerking begint en dien daarna een vervanging in. Bewaar een groep Bird-bericht-ID's als je SparkPost's campagnegebaseerde annulering wilt vervangen.

Stel BIRD_API_KEY in op je Bird-sleutel. Dit sandbox-voorbeeld vereist geen geverifieerd domein en bereikt geen echte inbox. Gebruik voor een EU-sleutel https://eu1.platform.bird.com:

curl --fail-with-body https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "onboarding@messagebird.dev",
    "to": ["delivered@messagebird.dev"],
    "subject": "Your receipt",
    "text": "Thanks for your order, {{ first_name }}.",
    "parameters": {"first_name": "Alex"},
    "category": "transactional",
    "metadata": {"order_id": "order_123"},
    "tags": [{"name": "mailstream", "value": "receipts"}]
  }'

Verwacht 202 Accepted en een em_-bericht-ID. Sla dat ID op en volg ontvangersresultaten via events. Acceptatie betekent niet dat het is afgeleverd: een onderdrukte ontvanger kan geaccepteerd en later afgewezen worden. Werk het parsen van het antwoord, foutafhandeling en idempotent opnieuw proberen bij met de verzendaanroep.

Lees voor een batch de data-array en sla het ID van elk bericht op bij je eigen verzendrecord. Bird valideert de batch vóór het in de wachtrij plaatsen: één ongeldig bericht kan het hele verzoek afwijzen. Splits grote transmissies zodat ze binnen de batchlimieten passen, en volg de retry-regels van Bird wanneer een antwoord onduidelijk is.

Geef elk afzonderlijk verzoek of batchchunk een eigen stabiele idempotentiesleutel. Het replayvenster van Bird verschilt van dat van SparkPost; bewaar je verzendrecords in de applicatie langer dan dat venster om duplicaten tijdens cutover of rollback te voorkomen.

SMTP-verzenders migreren

Gebruik de SMTP-verbindingsinstellingen van Bird, gebruikersnaam bird, en een API-sleutel met e-mailverzending ingeschakeld. Controleer de regio, TLS en de sleutelconfiguratie.

Converteer SparkPost's X-MSYS-API-opties voordat je de header verwijdert. Stel categorie, tags, tracking en poolstandaarden in via de SMTP-configuratie van Bird. Die instellingen gelden per API-sleutel; gebruik afzonderlijke geconfigureerde sleutels of HTTP wanneer ze per bericht verschillen. Gebruik HTTP voor metadata of templateparameters per bericht.

Zet elke afleversontvanger in de SMTP-envelope, zichtbare ontvangers in de MIME To/Cc-headers, en Bcc-ontvangers alleen in de envelope. Inventariseer X-MSYS-API.archive apart: SparkPost-archiefkopieën behouden de tracking-URL's van de oorspronkelijke ontvanger, dus gewone Bcc is niet gelijkwaardig. Valideer een vervanging voordat je die stroom overschakelt.

Kopieer je effectieve trackinginstellingen expliciet: de niet-geconfigureerde SMTP-sleutel van Bird schakelt open- en kliktracking in, terwijl de standaardinstellingen van SparkPost per account verschillen. Stel ook de categorie in: Bird SMTP staat standaard op transactioneel en inline HTTP op marketing. Nieuwsbriefverzenders hebben marketing nodig op beide paden.

Hergebruik bij SMTP-retries de idempotentiesleutel, envelope en exacte MIME-bytes. Het opnieuw genereren van Date, Message-ID of MIME-boundaries wijzigt de payload en kan een veilige retry verhinderen.

Templates converteren

Exporteer de versies die je daadwerkelijk verstuurt via SparkPost's Templates API: maak een lijst met GET /api/v1/templates?draft=false en haal de inhoud op met GET /api/v1/templates/{id}?draft=false. Sla concepten apart op als dat nodig is. Neem ook templates op die gedeeld worden met subaccounts en gerefereerde snippets in de inventaris.

SparkPost's templatetaal en de Liquid-syntax van Bird verschillen. Converteer conditionals, loops, standaardwaarden en geneste waarden. Los ontvanger-overrides en metadata die voor rendering worden gebruikt op tot expliciete parameters. Bijvoorbeeld: {{ if ... }} wordt {% if ... %}. Gedeelde {{ name }}-syntax alleen garandeert geen compatibiliteit.

Vouw snippets uit vóór publicatie; de Liquid-engine van Bird ondersteunt include of render niet. Vervang bij opgeslagen templates externe referenties zoals {{ user.name }} door platte parameters zoals {{ user_name }}. Als je dynamische HTML invoegt via SparkPost-parameters, render die dan in je applicatie en dien de voltooide body in zonder inline parameters; gewone HTML-parameterwaarden worden ge-escaped.

Maak een Bird-template aan, bekijk een voorbeeld en publiceer het. Volg daarna verzenden met een template. Neem de effectieve afzender, Reply-To en aangepaste headers van SparkPost over in het verzendverzoek; Bird-templates leveren de inhoud.

Voeg voor inline Liquid parameters toe, ook {}; als je het weglaat, blijven tokens ongewijzigd. Controleer ontbrekende waarden, escaping en URL's.

Vervang uitschrijf-placeholders door {{ bird.unsubscribe_url }}. Bird levert marketing-uitschrijfheaders; verwijder aangepaste List-Unsubscribe- en List-Unsubscribe-Post-headers uit marketingverzendingen om een 422-afwijzing te voorkomen.

De uitschrijflinks van Bird melden het adres af voor marketinge-mail in de hele werkruimte. Deze links bieden geen lijstspecifieke afmeldingen. Controleer dit gedrag als je SparkPost-integratie afzonderlijke abonnementen biedt.

Ontvangerslijsten verplaatsen

Exporteer elke opgeslagen ontvangerslijst met GET /api/v1/recipient-lists/{id}?show_recipients=true om lidmaatschap en personalisatie mee te nemen. Maak bestemmings-audiences aan en registreer contacteigenschappen voordat je importeert. Controleer elk importresultaat en stem lidmaatschapsaantallen af.

Contacteigenschappen horen bij het contact over al zijn audiences heen. Als hetzelfde adres verschillende substitutiegegevens heeft in meerdere SparkPost-lijsten, stem die waarden dan af voordat je importeert om overschrijven te voorkomen. Bird-contacteigenschappen hebben scalaire typen; bewaar lijstspecifieke of gestructureerde personalisatie in je applicatie als deze niet veilig kan worden weergegeven.

Gebruik broadcasts wanneer een gepubliceerd template kan worden gevuld vanuit contacteigenschappen. Audiencelidmaatschap wordt bepaald op het moment dat de verzending start, en de verzend- en concurrencylimieten van broadcasts gelden. Gebruik onafhankelijke batchberichten voor verzoekspecifieke parameters of een vaste momentopname van ontvangers. Valideer toestemming en suppressieafhandeling voordat je een gemigreerde lijst activeert.

Suppressies exporteren

Exporteer vóór productieverzending. Begin met GET /api/v1/suppression-list?cursor=initial&types=transactional,non_transactional,open_tracking en volg de paginering tot het einde. Sla de volledige records op, inclusief type, bron, lijst-ID, subaccount en tijdstempels. Gebruik X-MSYS-SUBACCOUNT: 0 voor het primaire account en elk subaccount-ID voor zijn eigen lijst. Zie SparkPost's Suppression List API.

Classificeer records op type, bron en bereik voordat je de importlus uit de hoofdgids gebruikt. Bird's POST /v1/email/suppressions accepteert een email en maakt een handmatige, werkruimtebrede blokkering op beide categorieën aan:

• Adressen geblokkeerd voor het ontvangen van e-mail: importeer de adressen die over alle categorieën heen geblokkeerd moeten worden. Bewaar de originele export voor afstemming; geïmporteerde records krijgen de handmatige reden van Bird.
• Accountbrede marketing-afmeldingen: gebruik POST /v1/preferences met channel: "email", het adres in handle, status: "revoked" en coverage: "non_transactional". Stel source: "sparkpost-migration" in voor reconciliatie. Controleer eerst bestaande Bird-voorkeuren en behoud strengere beperkingen; inspecteer applied en de geretourneerde voorkeur na elke schrijfactie.
• Lijstspecifieke of alleen-transactionele beperkingen: behoud hun scope in de verzendgeschiktheid van je applicatie. De e-mailvoorkeuren van Bird gelden kanaalbreed en kunnen deze scopes niet weergeven. Een handmatige suppressie kan ook wachtwoordresets blokkeren. Houd betrokken verkeer gepauzeerd totdat je de vervanging hebt geverifieerd.
• Open-tracking-afmeldingen: stel track_opens: false in voor het onafhankelijke bericht, naast eventuele verzendbeperkingen. Gebruik voor SMTP een sleutel met open tracking uitgeschakeld of gebruik HTTP voor controle per bericht.

Het voorkeurverzoek hierboven registreert de beperking op het moment van import. Bewaar de oorspronkelijke tijdstempels van SparkPost in je export en verifieer eventuele latere toestemming voordat je schrijft. Verifieer geïmporteerde records en mislukte schrijfacties en test vervolgens beide categorieën. Synchroniseer nieuwe afmeldingen en suppressies zolang beide providers verzenden. Blijf afmeldingen uit eerder afgeleverde SparkPost-mail toepassen op Bird na de cutover. Zie Suppressies voor de afhandeling van native bounces en klachten.

Webhook-events vertalen

SparkPost verstuurt gebatchte webhook-events onder msys-wrappers. Bird levert één event per request met type, timestamp en data. Registreer een Bird-endpoint met expliciete event-subscriptions en handtekeningverificatie. Houd de SparkPost-handler actief voor het resterende verkeer.

Directe API- en SMTP-verzendingen sturen email.accepted vóór verwerking. Broadcasts registreren acceptatie in de events API en het e-maillog, maar slaan die webhook over. SparkPost's policy_rejection, generation_failure en generation_rejection worden email.rejected; inspecteer rejection_reason. Dedupliceer opens apart bij het tellen van unieke engagement.

Gebruik data.email_id en data.recipient_id voor Bird-correlatie, en neem je eigen identifiers mee in metadata. Vervang SparkPost's batch-ID-afhandeling door Bird's regels voor webhookdeduplicatie en -volgorde. Lees bouncedetails voordat je beslist of een adres onderdrukt moet worden; bounceclassificatie maakt onderscheid tussen permanente adresfouten en tijdelijke of beleidsmatige fouten.

Bewaar rapportagehistorie

Exporteer de SparkPost-eventhistorie en geaggregeerde rapporten die je nodig hebt voordat hun bewaartermijnen verlopen. Volg eventpaginering tot het einde en bewaar provider-ID's, account-/subaccountscope, tijdstempels en rapportagefilters. Blijf late events verzamelen tijdens de overlap en bewaar de SparkPost-historie in een apart archief.

Sla een baseline op voor elke verzendstroom. Vergelijk overeenkomende ontvangergroepen en rapportageperiodes, en controleer metriekdefinities: provideracceptatie, aflevering bij de ontvangende server, unieke engagement en vooraf opgehaalde opens zijn verschillende maatstaven. Overeenkomende metrieknamen alleen maken de gemeten percentages niet vergelijkbaar.

Migreer inkomende e-mail apart

Als je SparkPost relay webhooks gebruikt, volg dan E-mail ontvangen voor die stroom. De email.received-webhook van Bird levert een inbound_message_id; haal de body, bijlagen of ruwe MIME op via de API in plaats van het volledige bericht in de webhook te verwachten. Test je handler met een Bird-doorstuuradres en bereid domeinontvangst voor voordat je MX-records wijzigt. Controleer de antwoordroutering na de DNS-wijziging en archiveer content die je nodig hebt na de bewaarperiode voor ontvangst van Bird.

Verifiëren en overschakelen

1. Verifieer de verzendcapaciteit van elk domein. Voer de sandbox-rooktest en klachtscenario's uit. Bevestig dat ondertekende events je handler bereiken, correleren met het juiste bericht en dat dubbele afleveringen worden afgehandeld. Sandbox-events bewijzen geen inboxaflevering, rendering of tracking.
2. Verstuur vanaf je geverifieerde domein naar gecontroleerde echte inboxen. Controleer personalisatie, To/Cc/Bcc-zichtbaarheid, bijlagen, authenticatie en tracking. Test een uitschrijving: marketing moet stoppen terwijl in aanmerking komende transactionele mail doorgaat. Test apart of blokkades voor alle categorieën beide weigeren. Houd deze controles gescheiden van gesimuleerde sandbox-resultaten.
3. Wijs lopende geplande verzendingen toe aan één provider. Drain of annuleer het origineel voordat je het elders opnieuw aanmaakt. Houd in je applicatie bij welke provider elke logische verzending heeft geaccepteerd, zodat nieuwe pogingen of rollback geen tweede kopie versturen.
4. Verplaats een gecontroleerd deel van het verkeer en monitor aflevermetrieken en webhookverwerking. Volg voor dedicated IP's het migratieplan dat met ons team is afgesproken, inclusief eventuele opwarming. Verhoog het verkeer nadat de waargenomen resultaten aan je afleververeisten voldoen.
5. Als validatie mislukt, pauzeer het getroffen Bird-verkeer en routeer nieuwe verzendingen via het behouden SparkPost-pad met actuele opt-outs toegepast. Reconcilieer onduidelijke verzendingen voordat je ze opnieuw probeert. Verwijder oude credentials, webhooks en DNS nadat wachtrijen en late events zijn verwerkt; houd oude tracking- en uitschrijflinks functioneel voor eerder afgeleverde mail.

Als authenticatie mislukt, controleer het Bird-bearertoken en de regio. Als voorkeurimports 403 retourneren, controleer de preferences-schrijfrechten van de key voordat je verdergaat. Als personalisatie onjuist rendert, inspecteer de Liquid-conversie en parameters. Als transactionele mail onverwacht wordt geweigerd, controleer geïmporteerde handmatige suppressies. Gebruik het e-maillogboek en eventdetails om elke correctie te verifiëren.

Volgende stappen

• E-mail versturen: payloadvelden, personalisatie en asynchrone resultaten
• E-mailtemplates: preview, publicatie en Liquid-ondersteuning
• Suppressies: suppressieredenen en beheer
• Webhooks en events: handtekeningen, opnieuw proberen en replay