Sign inGet started

Migrare da Mailgun

Questa pagina mappa i parametri POST /v3/{domain}/messages di Mailgun, le liste di soppressione e gli eventi webhook su Bird. Segui la guida principale alla migrazione nell'ordine indicato e usa queste corrispondenze per i passaggi 1, 3 e 4.

Passa questo al tuo agente

Incolla questo in Claude Code, Cursor o Codex. L'agente lavora su questa pagina partendo dal tuo repository, usando qualsiasi superficie Bird già disponibile: il server MCP se è collegato, la CLI se è installata e autenticata.
Esempio di codice
I am moving an email integration from Mailgun to Bird. Route through it with me.
1. Check what you already have before setting anything up. If Bird's MCP server is connected, use its tools. If the Bird CLI is installed and signed in, use that. Either one is enough, and every step below is an action you take with whichever you have. Only if neither is present, follow https://bird.com/docs/ai/set-up-your-agent.md to set one up and sign me in. Every Bird docs page serves Markdown at its own URL with `.md` appended, so fetch that rather than the HTML.
2. Read https://bird.com/docs/guides/email/migrate/mailgun.md for the parameter, suppression and event mapping, and https://bird.com/docs/guides/email/migrate.md for the order the steps go in.
3. Find and list my Mailgun usage in this repository before you change anything: the /v3/{domain}/messages call sites and any SDK wrappers around them, every o:, v: and h: prefixed parameter I pass, my webhook handler and the URL it is registered at, and every Mailgun domain I send from. Mailgun scopes almost everything per domain, so keep that list of domains: the next two steps both work through it.
4. Register each of those sending domains with Bird and give me the DNS records to publish, following https://bird.com/docs/guides/email/sending-domains.md. Leave every DNS record Mailgun uses exactly as it is: Bird's records are published alongside them and both providers authenticate side by side until I switch traffic. Publishing DNS affects mail for the whole domain, so show me the records and let me publish them.
5. Export my suppressions from Mailgun and import them into Bird before any production traffic goes through Bird, so my first sends do not reach addresses that already bounced or complained. Mailgun keeps three lists per domain, so pull GET /v3/{domain}/bounces, GET /v3/{domain}/complaints and GET /v3/{domain}/unsubscribes for every domain you found. The Bird import takes one address per request and is idempotent, so a partial re-run is safe. https://bird.com/docs/guides/email/suppressions.md has the reason taxonomy.
6. Port the send call and the webhook handler using the mapping tables on the provider page. Two things need attention rather than translation: Mailgun reports one failed event with a severity field where Bird has separate deferred and bounced events, and Bird signs deliveries per Standard Webhooks rather than Mailgun's scheme, so treat verification as a rewrite. See https://bird.com/docs/guides/webhooks.md and https://bird.com/docs/guides/email/events.md.
7. Run my whole integration against Bird's mail sandbox before any production traffic, following https://bird.com/docs/guides/email/testing-sandbox.md. Sandbox sends run the real pipeline without reaching an inbox or touching my sending reputation.
8. Stop and ask me wherever a step needs a decision. Do not point production traffic at Bird until I have seen the sandbox results and replied with the words cut over to Bird. Retiring the Mailgun path is a separate step that comes later: ask me again and wait for me to reply with the words retire the Mailgun path. A reply that agrees without naming what it is authorising is not authorisation. Finish by telling me what is left that only a person can do.

Mappa la chiamata di invio

I prefissi dei parametri form-encoded di Mailgun (opzioni o:, variabili v:, header h:) diventano tutti campi JSON di primo livello su POST /v1/email/messages:
FunzioneMailgunBird
Mittentefromfrom
Destinatarito / cc / bccto / cc / bcc (array)
Oggettosubjectsubject
Corpohtml / texthtml / text (almeno uno)
Reply-toh:Reply-Toreply_to (array)
Header personalizzatih:X-*headers (oggetto string → string)
Etichette filtrabilio:tagtags: coppie {name, value}
Contesto round-tripv:* / X-Mailgun-Variablesmetadata: JSON arbitrario
Template salvatotemplate + t:variablestemplate + template.parameters
Pianificazioneo:deliverytimescheduled_at
Tracciamento aperture/clico:tracking-opens / o:tracking-clickstrack_opens / track_clicks (default true)
Categoria(nessuno)category: marketing (default) o transactional
I limiti e i valori predefiniti dei campi (numero di destinatari, limiti di tag e metadati) sono in Invio email.
Note sul porting:
  • La richiesta diventa JSON. Mailgun accetta dati multipart form. Noi accettiamo un body JSON con Content-Type: application/json. Questa è di solito la modifica meccanica più grande nel porting.
  • Le variabili v: venivano restituite negli eventi. Il nostro metadata funziona allo stesso modo. Restituiamo i tuoi metadata (e tags) in ogni evento webhook insieme a email_id/recipient_id, così i tuoi handler li ricevono senza una ricerca aggiuntiva.
  • Le variabili destinatario non si portano uno a uno. Le recipient-variables di Mailgun personalizzano molti destinatari in una sola chiamata. Qui quel compito spetta al batch endpoint, un elemento per destinatario, ciascuno con il proprio contenuto o i propri valori parameters per la sostituzione {{ token }}.
  • I template salvati si portano direttamente. Il parametro template di Mailgun corrisponde al nostro campo template con i valori in template.parameters. Vedi invio con un template.
  • Gli allegati si portano direttamente. I file multipart attachment / inline di Mailgun diventano il nostro array attachments con content in base64 (imposta content_id per le immagini inline). Vedi allegati.

Esporta le soppressioni

Mailgun mantiene tre liste per dominio. Esporta ciascuna ed eseguile nel ciclo di importazione:
  • GET /v3/{domain}/bounces
  • GET /v3/{domain}/complaints
  • GET /v3/{domain}/unsubscribes
Ripeti per ogni dominio di invio. Le liste di Mailgun hanno ambito per dominio, mentre le nostre soppressioni hanno ambito per spazio di lavoro: quello che importi è l'unione delle liste di tutti i tuoi domini.

Traduci gli eventi webhook

Mailgun segnala errori temporanei e permanenti con un unico evento failed più un campo severity. Noi li separiamo:
EsitoMailgunBird
Accettato/elaboratoacceptedemail.acceptedemail.processed
Consegnatodeliveredemail.delivered
Errore temporaneofailed (temporary)email.deferred
Bounce permanentefailed (permanent)email.bounced / email.out_of_band_bounce
Segnalazione spamcomplainedemail.complained
Bloccato/soppresso(nessuno)email.rejected
Aperturaopenedemail.opened
Clicclickedemail.clicked
Disiscrizioneunsubscribedemail.list_unsubscribed
email.rejected non ha un corrispettivo in Mailgun: segnaliamo i destinatari soppressi in modo visibile (stato rejected, rejection_reason: recipient_suppressed) invece di saltarli silenziosamente. Aggiungi un handler dedicato invece di trattarlo come un bounce.
Anche la verifica cambia: Mailgun firma con un HMAC su timestamp + token dentro l'oggetto signature del payload, mentre noi firmiamo secondo la specifica Standard Webhooks, con header anziché campi nel payload. Sostituisci il tuo codice di verifica con la ricetta in Webhooks & events.

Passaggio in produzione

Segui domini e DNS e lo smoke test in sandbox nella guida principale. Entrambi sono indipendenti dal provider.

Prossimi passi

  • Domini di invio: registrazione, ciclo di vita della verifica e i record DNS che stai reindirizzando
  • Webhooks & events: configurazione degli endpoint e verifica Standard Webhooks
  • Sandbox di test: testa la nuova integrazione prima del passaggio in produzione
  • Soppressioni: verifica la lista importata e come la manteniamo da qui in poi