Migrazione da SparkPost

Usa questa guida per spostare l'email in uscita da SparkPost a Bird. Segui la checklist principale di migrazione, utilizzando le mappature seguenti per la tua integrazione HTTP o SMTP.

Prima di iniziare

Ti serve accesso al tuo account SparkPost e ai subaccount, al DNS del dominio di invio, alla configurazione dell'applicazione e al gestore webhook. Prepara uno spazio di lavoro Bird e una chiave API nella regione scelta. L'importazione degli opt-out richiede anche il permesso di scrittura preferences sulla chiave.

Fai l'inventario di mittenti, template, snippet, liste di destinatari, soppressioni, invii programmati, pool IP e webhook. Includi SDK, mail adapter dei framework, job in background e flussi email in ingresso. Registra i nuovi ID delle risorse man mano che li crei; gli ID e le credenziali SparkPost non funzionano in Bird. Usa gli SDK Bird quando sostituisci un client SparkPost, e verificane i retry, i timeout e la paginazione.

Se usi i subaccount SparkPost, contattaci prima di scegliere il layout dello spazio di lavoro. Verifica gli spazi di lavoro disponibili, i permessi, le risorse condivise e il flusso di provisioning dei tenant. Una chiave API dello spazio di lavoro non può cambiare tenant con X-MSYS-SUBACCOUNT. Mantieni i tenant sospesi e le restrizioni di invio specifiche per tenant durante la migrazione.

Verifica che le quote del piano Bird e i limiti delle richieste coprano il tuo volume di invio, il numero di risorse e il traffico di picco.

Registra i tuoi domini di invio in anticipo. Mantieni il DNS SparkPost funzionante e scegli hostname separati per return-path e tracking dove necessario. Se la registrazione segnala un conflitto di proprietà, contatta il supporto prima di rimuovere un dominio attivo.

IP dedicati: Contattaci o contatta il tuo account team prima della migrazione. Chiedici di confermare se i tuoi IP SparkPost esistenti possono essere trasferiti su Bird e concorda la configurazione dei pool, la tempistica e l'eventuale warmup necessario. Includi la regione dell'account, gli indirizzi IP, i nomi dei pool e il volume di invio. Mantieni attivi gli IP attuali finché il piano di migrazione non è confermato.

Verifica la selezione del pool e le allowlist di IP o hostname dei destinatari prima del cutover. L'acquisto di un IP non cambia il pool predefinito. Gli IP appena acquistati possono inviare il traffico in eccesso attraverso l'infrastruttura condivisa durante il warmup, cosa importante se i destinatari accettano email solo da IP specifici.

Passa questo al tuo agente

Incolla questo nel tuo agente di codifica nel repository della tua applicazione:

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.

Mappa la chiamata di invio

Sostituisci POST /api/v1/transmissions con POST /v1/email/messages, oppure con POST /v1/email/batches per messaggi indipendenti. La panoramica API di SparkPost elenca i suoi host regionali e l'autenticazione. Bird usa https://us1.platform.bird.com o https://eu1.platform.bird.com, in base alla regione della chiave API, con Authorization: Bearer $BIRD_API_KEY.

Una trasmissione SparkPost può generare email separate e personalizzate per i suoi destinatari. Bird condivide contenuto e parametri tra i destinatari di un singolo invio. Usa un messaggio separato per ogni personalizzazione, raggruppandoli facoltativamente in un batch. Gli invii solo-To restano indirizzati singolarmente; verifica gli header visibili quando aggiungi copie Cc/Bcc.

Mappa i campi della trasmissione SparkPost:

Per copie To/Cc/Bcc di una singola email, ricostruisci il gruppo di destinatari una sola volta. Gli indirizzi visualizzati di SparkPost possono differire dai destinatari di consegna; to, cc e bcc di Bird aggiungono ciascuno destinatari di consegna. Copiare un header CC di SparkPost nel cc di ogni messaggio espanso può generare copie duplicate. Verifica gli header visibili e il conteggio dei destinatari prima di effettuare il passaggio.

Controlla i limiti dei campi di invio, la programmazione e le regole sugli allegati. Aggiorna gli ID delle immagini inline e i riferimenti cid: corrispondenti per rispettare le regole di Bird. Configura il return path e il dominio di tracking sul dominio.

I campi di invio HTTP di Bird non includono content.email_rfc822, content.amp_html o options.inline_css di SparkPost. Ricostruisci i messaggi raw con i campi supportati, fornisci fallback HTML/text per AMP e incorpora il CSS inline prima di inviare l'HTML. SMTP analizza e ricostruisce le parti supportate del messaggio; valida il MIME ricevuto se dipendi dalla sua struttura esatta. I parametri MIME degli allegati come method per i calendari o charset per il testo non vengono preservati.

Per i messaggi API programmati, Bird fissa la versione del template, la lingua e i parametri al momento dell'accettazione della richiesta. Le modifiche successive al template non aggiornano quel messaggio. Per modificarlo, annulla il messaggio programmato prima che l'elaborazione inizi, quindi invia un sostituto. Conserva un gruppo di ID messaggio Bird se devi sostituire la cancellazione basata su campagna di SparkPost.

Imposta BIRD_API_KEY sulla tua chiave Bird. Questo esempio sandbox non richiede un dominio verificato e non raggiunge nessuna casella reale. Per una chiave EU, usa 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"}]
  }'

Aspettati 202 Accepted e un ID messaggio em_. Salva quell'ID e segui gli esiti per il destinatario attraverso gli eventi. L'accettazione non garantisce la consegna: un destinatario soppresso può essere accettato e successivamente rifiutato. Aggiorna il parsing della risposta, la gestione degli errori e i tentativi idempotenti insieme alla chiamata di invio.

Per un batch, leggi l'array data e salva l'ID di ogni messaggio associandolo al tuo record di invio. Bird valida il batch prima di accodarlo: un singolo messaggio non valido può causare il rifiuto dell'intera richiesta. Suddividi le trasmissioni più grandi per rispettare i limiti del batch e segui le regole di ripetizione di Bird quando una risposta è ambigua.

Assegna a ogni richiesta distinta o porzione di batch una propria chiave di idempotenza stabile. La finestra di replay di Bird è diversa da quella di SparkPost; conserva i record di invio della tua applicazione oltre tale finestra per evitare duplicati durante il cutover o il rollback.

Migrare i mittenti SMTP

Usa le impostazioni di connessione SMTP di Bird, lo username bird e una chiave API con l'invio email abilitato. Verifica la regione, TLS e la configurazione della chiave.

Converti le opzioni X-MSYS-API di SparkPost prima di rimuovere l'header. Imposta categoria, tag, tracking e pool predefiniti nella configurazione SMTP di Bird. Queste impostazioni si applicano per chiave API; usa chiavi configurate separate o HTTP quando variano tra i messaggi. Usa HTTP per metadati o parametri di template per singolo messaggio.

Inserisci ogni destinatario di consegna nell'envelope SMTP, i destinatari visibili negli header MIME To/Cc e i destinatari Bcc solo nell'envelope. Inventaria X-MSYS-API.archive separatamente: le copie di archivio di SparkPost conservano gli URL di tracking del destinatario originale, quindi un normale Bcc non è equivalente. Valida un'alternativa prima di cambiare quel flusso.

Copia esplicitamente le impostazioni di tracking effettive: una chiave SMTP non configurata di Bird abilita il tracking di apertura e clic, mentre i valori predefiniti di SparkPost variano in base all'account. Imposta anche la categoria: Bird SMTP usa transactional come predefinito e HTTP inline usa marketing. I mittenti di newsletter hanno bisogno di marketing su entrambi i percorsi.

Per i tentativi SMTP, riutilizza la chiave di idempotenza, l'envelope e gli stessi byte MIME. Rigenerare Date, Message-ID o i boundary MIME modifica il payload e può impedire un tentativo sicuro.

Convertire i template

Esporta le versioni che effettivamente invii tramite l'API Templates API di SparkPost: elenca con GET /api/v1/templates?draft=false, poi recupera il contenuto con GET /api/v1/templates/{id}?draft=false. Salva le bozze separatamente se necessario. Includi nell'inventario i template condivisi con i subaccount e gli snippet referenziati.

Il linguaggio dei template di SparkPost e la sintassi Liquid di Bird sono diversi. Converti condizionali, cicli, valori predefiniti e valori annidati. Risolvi gli override dei destinatari e i metadati usati per il rendering in parametri espliciti. Ad esempio, {{ if ... }} diventa {% if ... %}. La sola sintassi {{ name }} condivisa non garantisce la compatibilità.

Espandi gli snippet prima della pubblicazione; il Liquid di Bird non supporta include o render. Per i template archiviati, sostituisci i riferimenti esterni come {{ user.name }} con parametri piatti come {{ user_name }}. Se inserisci HTML dinamico tramite i parametri di SparkPost, esegui il rendering nella tua applicazione e invia il corpo completato senza parameters inline; i valori HTML ordinari dei parametri vengono sottoposti a escaping.

Crea, visualizza in anteprima e pubblica un template Bird, quindi segui invio con un template. Riporta il mittente effettivo, il Reply-To e gli header personalizzati da SparkPost nella richiesta di invio; i template Bird forniscono il contenuto.

Per il Liquid inline, includi parameters, anche {}; ometterlo lascia i token invariati. Verifica valori mancanti, escaping e URL.

Sostituisci i segnaposto di disiscrizione con {{ bird.unsubscribe_url }}. Bird fornisce gli header di disiscrizione marketing; rimuovi gli header personalizzati List-Unsubscribe e List-Unsubscribe-Post dagli invii marketing per evitare un rifiuto 422.

I link di disiscrizione di Bird escludono l'indirizzo dalle email marketing dell'intero spazio di lavoro. Questi link non forniscono opt-out specifici per lista. Verifica questo comportamento se la tua integrazione SparkPost offre iscrizioni separate.

Sposta le liste di destinatari

Esporta ogni lista di destinatari archiviata con GET /api/v1/recipient-lists/{id}?show_recipients=true per includere appartenenza e personalizzazione. Crea le audience di destinazione e registra le proprietà del contatto prima dell'importazione. Controlla il risultato di ogni importazione e riconcilia i conteggi di appartenenza.

Le proprietà del contatto appartengono al contatto in tutte le sue audience. Se lo stesso indirizzo ha dati di sostituzione diversi in più liste SparkPost, riconcilia quei valori prima dell'importazione per evitare di sovrascriverli. Le proprietà del contatto Bird hanno tipi scalari; mantieni nella tua applicazione la personalizzazione specifica per lista o strutturata quando non può essere rappresentata in modo sicuro.

Usa i broadcast quando un template pubblicato può essere popolato dalle proprietà del contatto. L'appartenenza all'audience viene risolta all'avvio dell'invio e si applicano le quote di invio e concorrenza dei broadcast. Usa messaggi batch indipendenti per parametri specifici della richiesta o uno snapshot fisso dei destinatari. Valida la gestione del consenso e delle soppressioni prima di attivare una lista migrata.

Esporta le soppressioni

Esporta prima dell'invio in produzione. Inizia con GET /api/v1/suppression-list?cursor=initial&types=transactional,non_transactional,open_tracking, quindi segui la paginazione fino al completamento. Salva i record completi, inclusi tipo, origine, ID della lista, subaccount e timestamp. Usa X-MSYS-SUBACCOUNT: 0 per l'account principale e l'ID di ogni subaccount per la propria lista. Vedi la Suppression List API di SparkPost.

Classifica i record per tipo, origine e ambito prima di usare il ciclo di importazione della guida principale. POST /v1/email/suppressions di Bird accetta un email e crea un blocco manuale, esteso all'intero spazio di lavoro, su entrambe le categorie:

• Indirizzi bloccati dalla ricezione di email: importa quelli che devono essere bloccati in tutte le categorie. Conserva l'esportazione originale per la riconciliazione; i record importati portano il motivo manuale di Bird.
• Opt-out marketing a livello di account: usa POST /v1/preferences con channel: "email", l'indirizzo in handle, status: "revoked" e coverage: "non_transactional". Imposta source: "sparkpost-migration" per la riconciliazione. Verifica prima le preferenze Bird esistenti e preserva le restrizioni più severe; controlla applied e la preferenza restituita dopo ogni scrittura.
• Restrizioni specifiche per lista o solo transazionali: preserva il loro ambito nell'idoneità all'invio della tua applicazione. Le preferenze email di Bird sono a livello di canale e non possono rappresentare questi ambiti. Una soppressione manuale può anche bloccare i reset delle password. Mantieni il traffico interessato in pausa finché non verifichi la sostituzione.
• Opt-out dal tracciamento delle aperture: imposta track_opens: false per il messaggio indipendente, in aggiunta a eventuali restrizioni di invio. Per SMTP, usa una chiave con il tracciamento delle aperture disabilitato oppure usa HTTP per il controllo per singolo messaggio.

La richiesta di preferenza sopra registra la restrizione al momento dell'importazione. Conserva i timestamp originali di SparkPost nel tuo export e riconcilia eventuali consensi successivi prima di scrivere. Riconcilia i record importati e le scritture fallite, quindi testa entrambe le categorie. Sincronizza nuovi opt-out e soppressioni mentre entrambi i provider inviano. Continua ad applicare gli opt-out dalle email SparkPost già consegnate a Bird dopo il cutover. Consulta Soppressioni per la gestione nativa di bounce e reclami.

Convertire gli eventi webhook

SparkPost invia eventi webhook in batch racchiusi in wrapper msys. Bird consegna un evento per richiesta con type, timestamp e data. Registra un endpoint Bird con sottoscrizioni esplicite agli eventi e verifica della firma. Mantieni attivo l'handler SparkPost per il traffico residuo.

Gli invii diretti API e SMTP emettono email.accepted prima dell'elaborazione. I broadcast registrano l'accettazione negli eventi API e nel log email, ma non emettono quel webhook. policy_rejection, generation_failure e generation_rejection di SparkPost corrispondono a email.rejected; ispeziona rejection_reason. Deduplica le aperture separatamente quando conteggi l'engagement unico.

Usa data.email_id e data.recipient_id per la correlazione Bird e inserisci i tuoi identificativi in metadata. Sostituisci la gestione dei batch-ID di SparkPost con le regole di deduplicazione e ordinamento dei webhook di Bird. Leggi i dettagli del bounce prima di decidere se un indirizzo debba essere soppresso; la classificazione dei bounce distingue i fallimenti permanenti dell'indirizzo da quelli temporanei o di policy.

Conservare lo storico dei report

Esporta lo storico degli eventi SparkPost e i report aggregati necessari prima della scadenza delle finestre di conservazione. Segui la paginazione degli eventi fino al completamento e conserva gli ID del provider, l'ambito account/subaccount, i timestamp e i filtri di reporting. Continua a raccogliere gli eventi in ritardo durante la sovrapposizione e conserva lo storico di SparkPost in un archivio separato.

Salva una baseline per ogni flusso di invio. Confronta popolazioni di destinatari e finestre di reporting corrispondenti e verifica le definizioni delle metriche: accettazione del provider, consegna al server destinatario, engagement unico e aperture prefetch sono misure diverse. La sola corrispondenza dei nomi delle metriche non stabilisce tassi confrontabili.

Migrare le email in entrata separatamente

Se usi i relay webhook di SparkPost, segui Ricezione email per quel flusso. Il webhook email.received di Bird fornisce un inbound_message_id; recupera il corpo, gli allegati o il MIME grezzo tramite la API invece di aspettarti il messaggio completo nel webhook. Testa il tuo handler con un indirizzo di inoltro Bird, poi prepara la ricezione sul dominio prima di modificare i record MX. Verifica l'instradamento delle risposte dopo la modifica DNS e archivia i contenuti di cui hai bisogno oltre il periodo di conservazione della ricezione di Bird.

Verifica e cutover

1. Verifica la capacità di invio di ciascun dominio. Esegui lo smoke test in sandbox e i casi di reclamo. Conferma che gli eventi firmati raggiungano il tuo handler, siano correlati al messaggio corretto e gestiscano le consegne duplicate. Gli eventi sandbox non dimostrano la consegna in inbox, il rendering o il tracking.
2. Invia dal tuo dominio verificato a caselle reali controllate. Controlla personalizzazione, visibilità To/Cc/Bcc, allegati, autenticazione e tracking. Testa una disiscrizione: il marketing deve fermarsi mentre la posta transazionale idonea continua. Testa separatamente che i blocchi su tutte le categorie rifiutino entrambe. Mantieni questi controlli distinti dai risultati simulati in sandbox.
3. Assegna gli invii programmati in sospeso a un solo provider. Svuota o annulla l'originale prima di ricrearlo altrove. Mantieni un registro applicativo di quale provider ha accettato ciascun invio logico, così che i tentativi ripetuti o il rollback non producano una seconda copia.
4. Sposta una porzione controllata di traffico e monitora le metriche di consegna e l'elaborazione dei webhook. Per IP dedicati, segui il piano di migrazione concordato con il nostro team, incluso qualsiasi warmup. Aumenta il traffico dopo che i risultati osservati soddisfano i tuoi requisiti di consegna.
5. Se la validazione fallisce, metti in pausa il traffico Bird interessato e instrada i nuovi invii attraverso il percorso SparkPost mantenuto con gli opt-out correnti applicati. Riconcilia gli invii ambigui prima di riprovare. Ritira le vecchie credenziali, i webhook e il DNS dopo aver gestito le code e gli eventi tardivi; mantieni funzionali i link di tracking e disiscrizione esistenti per la posta già consegnata.

Se l'autenticazione fallisce, controlla il bearer token Bird e la regione. Se l'importazione delle preferenze restituisce 403, controlla il permesso di scrittura preferences della chiave prima di continuare. Se la personalizzazione viene renderizzata in modo errato, ispeziona la conversione Liquid e i parametri. Se la posta transazionale viene rifiutata inaspettatamente, controlla le soppressioni manuali importate. Usa il log email e i dettagli degli eventi per verificare ogni correzione.

Passaggi successivi

• Invio email: campi del payload, personalizzazione e risultati asincroni
• Template email: anteprima, pubblicazione e supporto Liquid
• Soppressioni: motivi delle soppressioni e gestione
• Webhook ed eventi: firme, tentativi e replay