Sign inGet started

Migrazione da Mandrill

Questa pagina mappa il payload messages/send di Mandrill (Mailchimp Transactional), la rejection blacklist e i webhook su Bird. Segui la guida principale alla migrazione nell'ordine indicato e usa queste corrispondenze per i passi 1, 3 e 4.
Due differenze strutturali dominano la migrazione. Mandrill annida tutto sotto un oggetto message e si autentica con una key nel corpo della richiesta. Noi accettiamo un payload piatto al livello superiore e un header Authorization: Bearer standard. Inoltre il type del destinatario in Mandrill (to/cc/bcc come campo su ogni indirizzo) diventa nei nostri array separati to/cc/bcc.

Passa questo al tuo agente

Incolla questo in Claude Code, Cursor o Codex. L'agente lavora su questa pagina nel tuo repository, usando qualsiasi superficie Bird già disponibile: il server MCP se è collegato, la CLI se è installata e con accesso effettuato.
Esempio di codice
I am moving an email integration from Mandrill 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/mandrill.md for the payload, 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 Mandrill usage in this repository before you change anything: the messages/send and messages/send-template call sites and any SDK wrappers around them, the webhook handler and the URL it is registered at, and every domain I send from. Mandrill authenticates with an API key passed in the request body rather than a header, so tell me every place that key appears in my code: the port changes how I authenticate, not just what I send, and that key is a secret currently sitting in a payload.
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 my current provider 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 rejects from Mandrill 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. Read the list through rejects/list, and skip the soft-bounce rows: those are transient failures rather than suppressions, and importing them would suppress addresses that are fine. Show me how many rows you skipped. 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. Move the API key out of the request body and into the Authorization header as a bearer token while you are there. Bird signs deliveries per Standard Webhooks rather than Mandrill's scheme, so treat verification as a rewrite rather than a URL change: 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 Mandrill path is a separate step that comes later: ask me again and wait for me to reply with the words retire the Mandrill 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

FunzioneMandrill (messages/send)Bird
Autenticazionekey nel corpo della richiestaHeader Authorization: Bearer bk_...
Mittentemessage.from_email / from_namefrom: stringa o { "email", "name" }
Destinatarimessage.to: [{ email, name, type }]to / cc / bcc: suddivisi per il campo type
Oggettomessage.subjectsubject
Corpomessage.html / message.texthtml / text (almeno uno)
Reply-tomessage.headers["Reply-To"]reply_to: array
Header personalizzatimessage.headersheaders: oggetto stringa → stringa
Etichette filtrabilimessage.tags: stringhe semplicitags: coppie { name, value }
Contesto round-tripmessage.metadatametadata: JSON arbitrario
Template salvatomessages/send-template + merge_varstemplate + template.parameters
Programmazionesend_atscheduled_at
Tracciamento aperture/clicmessage.track_opens / track_clickstrack_opens / track_clicks (default true)
Allegatimessage.attachments: { type, name, content }attachments: { content_type, filename, content }
Immagini inlinemessage.images: { type, name, content }attachments con content_id
Categoriaconvenzione subaccount / tagscategory: marketing (default) o transactional
I limiti e i valori predefiniti dei campi (numero di destinatari, limiti di tag e metadati) si trovano in Invio email.
Note sulla migrazione:
  • Appiattisci e ri-autentica. Rimuovi il wrapper message (i suoi campi passano al livello superiore) e sposta la chiave API dal corpo della richiesta nell'header Authorization. Il campo key non ha un equivalente qui.
  • Suddividi i destinatari per type. Mandrill contrassegna ogni destinatario come to, cc o bcc sull'oggetto indirizzo. Noi usiamo tre array separati. Durante la migrazione, raggruppa la lista to in base al campo type.
  • I tag diventano coppie nome/valore. I tag di Mandrill sono stringhe semplici ("welcome"). I nostri tag sono coppie { name, value }. Scegli un name stabile, ad esempio { "name": "category", "value": "welcome" }, in modo che filtri e analytics raggruppino come facevano le statistiche di Mandrill. metadata si porta direttamente come JSON.
  • I template salvati si portano, con un'avvertenza. Il messages/send-template di Mandrill diventa il nostro campo template (referenziato per ID o slug) con i valori in template.parameters. Vedi invio con un template. Le nostre variabili di template sono per messaggio e non per destinatario, quindi i merge_vars per destinatario diventano una voce batch per destinatario, ciascuna con il proprio parameters.
  • Gli allegati si portano direttamente. Il content base64 di Mandrill è il nostro content, e le images inline (referenziate come cid: nell'HTML) diventano voci attachments con content_id. Vedi allegati.

Esportare le soppressioni

Mandrill conserva gli indirizzi indesiderati nella sua rejection blacklist. Estraila con rejects/list API (oppure esporta dalla vista Rejection Blacklist). Ogni voce ha un motivo (hard-bounce, soft-bounce, spam, unsub, custom). Salta le righe soft-bounce perché descrivono errori transitori e non vere soppressioni. Passa il resto attraverso il ciclo di importazione.

Tradurre gli eventi webhook

Mandrill invia array di eventi in batch; mappa il valore event sul vocabolario degli eventi di Bird:
EsitoMandrillBird
Inviato / accettatosendemail.acceptedemail.processed
Consegnatodeliveredemail.delivered
Errore temporaneodeferralemail.deferred
Bounce permanentehard_bounceemail.bounced / email.out_of_band_bounce
Soft bouncesoft_bounceemail.deferred (poi email.bounced se desiste)
Segnalazione spamspamemail.complained
Disiscrizioneunsubemail.unsubscribed / email.list_unsubscribed
Rifiutato/bloccatorejectemail.rejected
Aperturaopenemail.opened
Clicclickemail.clicked
Due differenze da gestire nel codice:
  • L'accettazione si divide qui in due eventi. Il send di Mandrill indica che il messaggio è stato iniettato e delivered indica che il server ricevente lo ha accettato, la stessa distinzione che facciamo noi. La differenza è solo dalla nostra parte: separiamo l'accettazione (email.accepted) dall'elaborazione (email.processed) prima di email.delivered, quindi un handler che si basava solo su send ora ha due eventi tra cui scegliere.
  • Gli eventi sono per destinatario e firmati in modo diverso. I nostri eventi di consegna hanno recipient_id insieme a email_id, con un flusso per destinatario. Consegniamo un evento per richiesta e lo firmiamo secondo la specifica Standard Webhooks. Mandrill invece firma array in batch con un X-Mandrill-Signature HMAC. Vedi Webhook ed eventi per la verifica.

Passaggio in produzione

Segui domini e DNS e il test sandbox nella guida principale. Entrambi sono indipendenti dal provider.

Passi successivi

  • Domini di invio: registrazione, ciclo di vita della verifica e i record DNS che stai reindirizzando
  • Webhook ed eventi: configurazione dell'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 avanti