Sign inGet Started

Migrare da un altro provider

Usa questa guida per spostare l'email di produzione da un altro provider. Mappa la richiesta di invio, pubblica i record DNS, importa le soppressioni, traduci gli eventi webhook e testa l'integrazione prima di dirigere il traffico di produzione verso Bird.

Checklist della migrazione:

  1. Mappa la chiamata di invio verso POST /v1/email/messages
  2. Aggiorna i domini di invio e il DNS
  3. Importa la lista di soppressione
  4. Converti i webhook al nostro vocabolario eventi
  5. Verifica con la sandbox email prima del passaggio

I passaggi 1, 3 e 4 dipendono dal provider che stai lasciando. La tua guida al provider contiene la mappatura campo per campo del payload, dove esportare la lista di soppressione e la tabella di traduzione dei nomi degli eventi webhook.

1. Mappare la chiamata di invio

Abbiamo un unico endpoint di invio singolo, POST /v1/email/messages. Costruisci un payload JSON piatto (nessun wrapper personalizations, nessun assemblaggio MIME) con from, array to/cc/bcc, subject, html e/o text, una lista reply_to opzionale e headers per header email personalizzati. Un invio riuscito restituisce 202 Accepted con un ID messaggio prefissato da em_. Gli esiti di consegna arrivano in modo asincrono tramite webhook e gli endpoint di lettura. Il payload completo, con ogni limite di campo e valore predefinito, è in Invio email. La mappatura campo per campo dal tuo payload attuale è nella tua guida al provider. Se la tua applicazione invia tramite SMTP oggi, potresti non dover portare affatto la chiamata: accettiamo l'invio via SMTP nella stessa pipeline, il che riduce questo passaggio a uno scambio di credenziali.

Usa tags come dimensioni di filtro nelle liste messaggi, nelle analisi e nei riepiloghi della dashboard. Usa metadata per il contesto strutturato che Bird salva sul messaggio e restituisce nelle letture API. Anche gli eventi webhook possono includere questo contesto, ma gli eventi di disiscrizione possono restituire valori null. Consulta Tag e metadata per i limiti.

Prima di portare il codice, tieni conto di queste differenze:

  • Pianificazione, template salvati e allegati si portano tutti. Usa scheduled_at per l'invio pianificato. Usa template al posto del contenuto inline per i template salvati. Mappa i file nell'array allegati.
  • I destinatari soppressi vengono rifiutati, in modo visibile. Un indirizzo soppresso riceve comunque un recipient_id e compare nella lista destinatari del messaggio con stato rejected e un evento email.rejected (rejection_reason: recipient_suppressed), mai come uno scarto silenzioso. Anche quando tutti i destinatari sono soppressi, la richiesta viene comunque accettata con un 202. Ogni destinatario risulta rifiutato. Vedi Soppressioni.
  • Imposta category: "transactional" per la posta operativa. Un invio ha come valore predefinito marketing, e la categoria controlla la policy di soppressione: marketing blocca in caso di reclami e disiscrizioni, transactional consegna nonostante. Newsletter e campagne sono gestite correttamente dal valore predefinito. Contrassegna ricevute, reset password e posta operativa simile come transactional in modo che non siano bloccate da una disiscrizione.

2. Aggiornare domini e DNS

Registra ogni dominio di invio con POST /v1/email/domains o in Email > Domains, poi pubblica i record da dns_records. DKIM, il CNAME del return-path e una policy DMARC abilitano l'invio. Un record DMARC esistente, anche su un dominio padre, è sufficiente. Il CNAME di tracking abilita solo il tracciamento brandizzato di aperture e clic. Domini di invio copre i record, il ciclo di vita della verifica e il modello regionale. Usa lo splitter di record DNS se il tuo provider richiede un valore DKIM diviso, e il generatore di policy DMARC se hai bisogno di una policy.

Un record che la maggior parte dei provider ti fa pubblicare subito è deliberatamente assente: non pubblichi nessun record SPF sull'apex del tuo dominio. SPF viene valutato rispetto al dominio envelope-from, che il CNAME del return-path punta verso di noi, quindi SPF passa e si allinea senza toccare il tuo apex. Se il tuo vecchio provider ti aveva fatto aggiungere un include: al record SPF dell'apex, lascialo in posizione durante la transizione e rimuovilo dopo il passaggio. Non aiuta né danneggia la posta inviata tramite noi, e rimuoverlo libera uno dei 10 DNS lookup che SPF consente sull'apex. La spiegazione completa è in DKIM, SPF & DMARC.

Puoi pubblicare i nostri record mentre quelli del vecchio provider sono ancora attivi. Il record DKIM usa un selettore nostro. I CNAME di return-path e tracking sono nuovi hostname che scegli tu, e il tuo record DMARC esistente soddisfa il requisito così com'è. Entrambi i provider autenticano in parallelo finché non sei pronto a spostare il traffico. Lo stato del dominio è regionale, quindi registra il dominio in ogni regione da cui invii.

3. Importare le soppressioni

Porta la tua lista di soppressione prima di inviare traffico di produzione tramite noi. Altrimenti i tuoi primi invii raggiungono indirizzi che hanno già generato bounce o reclami presso il vecchio provider, danneggiando la reputazione che stai cercando di proteggere.

Esporta la lista dal tuo provider attuale (la tua guida al provider contiene gli endpoint esatti), poi aggiungi ogni indirizzo qui con POST /v1/email/suppressions:

Esempio di codice
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

Due cose da sapere su questo percorso di importazione:

  • Importi un indirizzo per richiesta. L'API delle soppressioni è CRUD a singola voce, quindi una lista grande significa iterare sugli indirizzi esportati. La chiamata è idempotente (201 per un nuovo record, 200 con il record esistente se l'indirizzo è già soppresso manualmente), quindi rieseguire un'importazione parziale è sicuro.
  • Gli indirizzi importati ricevono reason: manual, applies_to: all, che blocca ogni categoria, inclusa quella transazionale. È più restrittivo di un record di reclamo nativo, che blocca solo gli invii non transazionali, quindi se hai bisogno del comportamento sensibile alla categoria per indirizzi specifici, consulta la tassonomia dei motivi in Soppressioni.

Da qui in poi, gli hard bounce creano soppressioni a livello di spazio di lavoro e generano email_suppression.created, indipendentemente dall'attribuzione al Brand. Anche i reclami senza un'attribuzione affidabile al Brand creano soppressioni a livello di spazio di lavoro e generano email_suppression.created. I reclami attribuiti a un Brand registrano preferenze protette. Le disiscrizioni registrano preferenze. Sottoscrivi anche gli eventi di preferenza, anche per uno spazio di lavoro con un solo Brand, così il tuo sistema replica queste revoche del consenso e i consensi concessi in seguito. Gli eventi a livello di messaggio email.complained, email.unsubscribed e email.list_unsubscribed restano disponibili. Consulta Eventi email per la distinzione.

4. Convertire i webhook

Registra un endpoint con POST /v1/webhooks e sottoscrivilo a una lista esplicita di tipi di evento. I nostri nomi di evento seguono resource.action: email.accepted → email.processed → email.delivered nel percorso normale, con email.deferred, email.bounced, email.complained, email.rejected, email.opened, email.clicked e la coppia di disiscrizione a coprire il resto. La traduzione dei nomi evento dal vocabolario del tuo provider attuale è nella tua guida al provider. Gli schemi di payload per ogni evento sono nel riferimento eventi.

Correla gli eventi dei messaggi in uscita usando email_id e workspace_id; gli eventi del ciclo di vita del destinatario includono anche recipient_id. Salva la corrispondenza tra messaggio e cliente al momento dell'invio. Considera tags e metadata come contesto aggiuntivo quando presenti: email.unsubscribed e email.list_unsubscribed provenienti dai link di disiscrizione Bird restituiscono valori null per gli invii singoli, anche quando l'invio li includeva. Anche gli eventi di disiscrizione dei broadcast possono restituire null quando quel contesto non è disponibile.

Usa preference.revoked, preference.granted e preference.deleted come segnali per aggiornare la replica delle preferenze. Questi eventi identificano preference_id e transition_id, con canale, handle, Brand, mittente e ambito del topic; non includono ID dei messaggi né metadata di invio. Il loro timestamp indica il momento in cui la dichiarazione ha effetto, non una versione del record. Un reclamo arrivato in ritardo può revocare un consenso massivo successivo, e modifiche diverse possono avere lo stesso timestamp. Non determinare lo stato o la copertura attuali ordinando gli eventi o usando transition_id come sequenza di ordinamento.

Inizializza e mantieni una replica completa delle preferenze in questo ordine:

  1. Sottoscrivi gli eventi di preferenza e conserva in modo durevole le notifiche in arrivo prima di avviare la lettura iniziale.
  2. Popola la replica leggendo tutte le pagine della lista delle preferenze dello spazio di lavoro, senza filtri per canale, handle o Brand. In questo modo individui le revoche del consenso esistenti che non hanno mai generato una notifica per il tuo endpoint. Conserva per ogni record ID, canale, handle, Brand, mittente e ambito del topic.
  3. Elabora le notifiche conservate e quelle nuove recuperando la preferenza attuale ed elencando tutte le pagine per il canale e l'handle interessati. Confronta gli ambiti per rilevare eliminazioni e ricreazioni con un ID diverso. Riconcilia periodicamente anche l'intera lista non filtrata dello spazio di lavoro, inclusi i destinatari assenti dalle notifiche o dalla tua replica locale.

Le letture possono essere in ritardo rispetto a una modifica: riprova in caso di errori transitori o di stato mancante o più vecchio del previsto. Una lettura non riuscita o incompleta non deve rimuovere un blocco locale. Rimuovi un record eliminato solo dopo averne confermato l'assenza; conserva le preferenze e le soppressioni indipendenti. Questa replica converge nel tempo e non sostituisce i controlli che Bird esegue al momento dell'invio.

email_suppression.created identifica le aggiunte tramite suppression_id, workspace_id e email. Non esiste un evento per le eliminazioni di soppressioni da parte del cliente. Per individuare le rimozioni effettuate nella dashboard o tramite API, leggi periodicamente tutte le pagine della lista di soppressione dello spazio di lavoro e riconcilia in base all'ID della soppressione. Non rimuovere record dopo una scansione non riuscita o parziale; conferma i record mancanti con una lettura successiva prima di rimuoverli. Mantieni i record di soppressione separati dalle preferenze, così la rimozione di un blocco non può cancellarne un altro.

Firmiamo le consegne secondo la specifica Standard Webhooks, usando tre header: webhook-id, webhook-timestamp e webhook-signature, con un HMAC-SHA256 su {id}.{timestamp}.{raw body}. Se verifichi già le consegne Standard Webhooks da un'altra piattaforma, lo stesso identico codice di verifica funziona anche qui. Altrimenti, la procedura di verifica, il calendario dei nuovi tentativi e gli strumenti di replay sono in Webhook ed eventi. Le consegne avvengono almeno una volta e senza ordine garantito, quindi deduplica su webhook-id. Usa i timestamp degli eventi dei messaggi per mostrarne la cronologia; per preferenze e soppressioni usa la riconciliazione dello stato attuale descritta sopra.

5. Verificare nella sandbox prima del passaggio

Prima di spostare il traffico di produzione, prova la chiamata di invio portata e l'handler degli eventi dei messaggi con la sandbox email. Gli invii sandbox vanno a indirizzi magici su messagebird.dev e passano attraverso la vera pipeline di produzione: stesso 202, stessa sequenza di eventi, stesse consegne webhook firmate, senza mai raggiungere una casella di posta o toccare la tua reputazione.

I segnali della sandbox non scrivono record di soppressione o di preferenza per reclamo. Testa la tua replica separatamente con payload rappresentativi email_suppression.created, preference.revoked, preference.granted e preference.deleted tratti dai contratti degli eventi webhook, includendo due Brand che condividono lo stesso destinatario. Includi questi casi:

  • Una revoca del consenso invariata è precedente alla registrazione del webhook. L'inventario iniziale non filtrato la individua senza alcuna notifica; anche l'inventario periodico individua un record mancante dalla tua replica locale.
  • Una disiscrizione da un invio singolo ha tags e metadata null; la corrispondenza dei messaggi che hai salvato identifica comunque il cliente.
  • Un reclamo arriva dopo un consenso massivo più recente, oppure una revoca del consenso più vecchia valida per tutte le categorie amplia la protezione da reclamo senza far avanzare il suo timestamp di effetto. Consegna gli eventi in ordine inverso e verifica che la riconciliazione mantenga lo stato revocato e la copertura attuali.
  • Una preferenza viene eliminata e ricreata, oppure una soppressione manuale viene rimossa nella dashboard. La riconciliazione rimuove solo i record di cui è confermata l'assenza e mantiene i blocchi non correlati.
  • Un aggiornamento non riesce o restituisce temporaneamente uno stato più vecchio. Il tuo handler riprova e la riconciliazione periodica ripara la replica senza rimuovere blocchi in seguito alla lettura non riuscita.

Uno smoke test minimo pre-passaggio:

  1. Invia a delivered@messagebird.dev e verifica che il tuo handler elabori email.accepted → email.processed → email.delivered.
  2. Invia a bounce@messagebird.dev e verifica che la tua gestione bounce si attivi su email.bounced (i bounce simulati non scrivono nella tua lista di soppressione, quindi l'indirizzo resta riutilizzabile).
  3. Invia a suppressed@messagebird.dev e verifica di gestire email.accepted seguito da email.rejected, senza email.processed o eventi di consegna dopo. Questa è la forma che ogni destinatario soppresso produce in produzione; il dettaglio rejection_reason: recipient_suppressed è sul record del destinatario e sugli eventi API.
  4. Invia un messaggio category: "marketing" e conferma che la categoria compaia dove ti aspetti nella lettura del messaggio.

Usa il subaddressing +label (bounce+cutover-test@messagebird.dev) per correlare i casi di test. L'indirizzo completo compare nei tuoi eventi. Una volta superato lo smoke test, sposta il traffico. Punta la tua applicazione verso di noi e mantieni i DNS del vecchio provider in posizione finché i tuoi domini qui non mostrano capabilities.sending verificato. Monitora le prime ore di consegne reali nella dashboard e nel tuo flusso webhook.

Migrare da un provider specifico

  • SparkPost: transmissions e SMTP, conversione dei template, soppressioni con ambito ed eventi webhook
  • SendGrid: personalizations → payload piatto, categories/custom_args → tags/metadata, l'equivalenza dropped ↔ email.rejected
  • Mailgun: parametri o:*/v:*/h:* → campi di primo livello, esportazione bounces/complaints/unsubscribes
  • Amazon SES: SendEmail v2 → un unico endpoint, configuration sets → flag di tracking per messaggio, SNS → webhook firmati
  • Resend: struttura del payload quasi identica, webhook firmati Svix → Standard Webhooks
  • Postmark: destinatari separati da virgola → array, dump di soppressione per stream, webhook non firmati → firmati
  • Brevo: oggetti indirizzo → indirizzi semplici, due blocklist separate da esportare, params → template.parameters
  • MailerSend: cinque liste di soppressione di cui quella temporanea resta indietro, personalization → parametri per invio
  • Mailjet: l'array Messages → un unico payload piatto, EventPayload → metadata, esportazione blocklist
  • Mandrill: il wrapper message e autenticazione nel body → payload piatto e bearer auth, esportazione rejection blacklist

Prossimi passi

  • Invio email: il payload di invio completo, tag e metadata, il modello asincrono 202
  • Domini di invio: registrazione, ciclo di vita della verifica, configurazione multi-regione
  • DKIM, SPF & DMARC: cosa dimostra ogni record e perché SPF sull'apex non è richiesto
  • Soppressioni: motivi, categorie e l'API di gestione
  • Webhook ed eventi: configurazione endpoint, verifica Standard Webhooks, retry e replay
  • Eventi: schemi di payload per evento
  • Sandbox di test: la lista completa degli indirizzi magici e le procedure guidate
  • Riferimento API: schemi di richiesta e risposta per l'endpoint di invio