Documentazione
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

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, restituisce nelle letture API e riporta negli eventi webhook. 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 non gestisci i bounce da solo: sopprimi automaticamente hard bounce e reclami, generando email_suppression.created così i tuoi sistemi possono replicare la lista di soppressione. Le disiscrizioni vengono invece registrate come preferenza dichiarata e replicate tramite email.unsubscribed e email.list_unsubscribed, non tramite l'evento di soppressione.

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.
La correlazione si porta senza problemi. Ogni evento ha gli identificatori email_id, recipient_id e workspace_id. Riporta inoltre tags e metadata dalla richiesta di invio. Questo restituisce il contesto che il vecchio provider ti forniva tramite echo del payload, senza un lookup aggiuntivo. Inserisci i tuoi ID interni in metadata nell'invio e leggili direttamente da ogni evento.
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 qui. Altrimenti, la procedura di verifica, il programma di retry e gli strumenti di replay sono in Webhook ed eventi. Le consegne sono at-least-once e non ordinate, quindi deduplica su webhook-id e ordina per il timestamp del payload, la stessa disciplina che il tuo handler attuale dovrebbe già avere.

5. Verificare nella sandbox prima del passaggio

Prima di spostare il traffico di produzione, esegui la tua integrazione completa (la chiamata di invio portata, il tuo handler webhook, la replica delle soppressioni) contro 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.
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

  • 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

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaGetting started with emailEsplora la funzionalitàEmailSegui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Prova l'esercitazione e ottieni un brief di implementazione