Migrazione da Amazon SES
Questa pagina mappa la chiamata SES v2 SendEmail, la suppression list a livello di account e le notifiche eventi SNS 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 nel tuo repository, usando qualsiasi superficie Bird di cui dispone: il server MCP se connesso, la CLI se installata e autenticata.
Esempio di codice
I am moving an email integration from Amazon SES 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/ses.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 SES usage in this repository and its infrastructure before you change anything: the SendEmail and SendRawEmail call sites through the AWS SDK or CLI, the configuration sets they name, the SNS topics or EventBridge rules carrying my events, the handler subscribed to them, and every identity I send from. Say which of these live in infrastructure code rather than application code, because those change by a different route.
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 the SES DKIM CNAMEs exactly as they are: Bird's DKIM record uses its own selector, so the two coexist 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 account-level suppression list from SES and import it into Bird before any production traffic goes through Bird, so my first sends do not reach addresses that already bounced or complained. Read it from GET /v2/email/suppressed-destinations, paginating with NextToken to the end, and keep both the BOUNCE and COMPLAINT reasons. 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 replace the event plumbing. Bird posts signed webhooks straight to an endpoint, so the SNS topic, the subscription-confirmation handshake, and the message-envelope unwrapping all go away rather than being ported: my handler reads the event body directly and verifies it per Standard Webhooks. See https://bird.com/docs/guides/webhooks.md and https://bird.com/docs/guides/email/events.md. Tell me which SNS or EventBridge resources become unused, but do not delete any of them.
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 SES path is a separate step that comes later: ask me again and wait for me to reply with the words retire the SES 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
SES distribuisce un invio tra Destination, Content e il meccanismo dei configuration set. Il nostro POST /v1/email/messages è un unico payload piatto:
| Funzione | SES (SendEmail v2) | Bird |
|---|---|---|
| Mittente | FromEmailAddress | from |
| Destinatari | Destination.*Addresses | to / cc / bcc (array) |
| Oggetto | Content.Simple.Subject | subject |
| Corpo | Content.Simple.Body.Html/Text | html / text (almeno uno) |
| Reply-to | ReplyToAddresses | reply_to (array) |
| Header personalizzati | Content.Simple.Headers | headers (oggetto string → string) |
| Etichette filtrabili | EmailTags | tags: coppie {name, value} |
| Contesto round-trip | (nessuno) | metadata: JSON arbitrario |
| Template salvato | Content.Template | template + template.parameters |
| Tracciamento aperture/clic | configuration set | track_opens / track_clicks (default true) |
| Pool IP | dedicated IP pool (config set) | ip_pool_id (ipp_... o ipp_shared) |
| Categoria | (nessuno) | category: 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:
- I configuration set si dissolvono in campi per messaggio. Tracciamento, pool IP e routing degli eventi erano gestiti dai configuration set su SES. Qui i primi due sono campi del payload e il routing degli eventi è una sottoscrizione webhook.
- L'autenticazione passa da SigV4 a un bearer token. Nessuna firma della richiesta: un semplice header Authorization: Bearer bk_.... Rimuovi la catena di credenziali AWS SDK da questo percorso di codice.
- I template SES si trasferiscono in template salvati. Content.Template (nome del template più TemplateData) corrisponde al nostro campo template con i valori in template.parameters. Vedi invio con un template.
- Content.Raw (MIME) non ha un equivalente. Il messaggio viene costruito da campi strutturati. Se assembli MIME grezzo per allegare file, inviali come array attachments (base64 content per file, content_id per immagini inline).
- La sandbox SES ≠ sandbox Bird. La sandbox SES limita a chi puoi inviare. La nostra sandbox email è un simulatore con indirizzi magici: nessuna allowlist e nessun messaggio viene recapitato.
Esporta le soppressioni
Esporta la suppression list a livello di account e passala attraverso il ciclo di importazione:
- GET /v2/email/suppressed-destinations (pagina con NextToken; ogni voce ha BOUNCE o COMPLAINT come motivo)
Traduci gli eventi webhook
SES pubblica gli eventi tramite SNS o EventBridge. Noi inviamo webhook firmati in POST direttamente, quindi il topic SNS, l'handshake di conferma della sottoscrizione e l'unwrapping dell'envelope del messaggio non servono più. I nomi degli eventi si mappano così:
| Esito | SES | Bird |
|---|---|---|
| Accettato/elaborato | Send | email.accepted → email.processed |
| Recapitato | Delivery | email.delivered |
| Errore temporaneo | DeliveryDelay | email.deferred |
| Bounce permanente | Bounce | email.bounced / email.out_of_band_bounce |
| Segnalazione spam | Complaint | email.complained |
| Bloccato/soppresso | (nessuno) | email.rejected |
| Apertura | Open | email.opened |
| Clic | Click | email.clicked |
| Disiscrizione | Subscription | email.list_unsubscribed |
email.rejected è nuovo rispetto a SES: i destinatari soppressi vengono segnalati in modo visibile (stato rejected, rejection_reason: recipient_suppressed) anziché conteggiati nel ciclo invio-e-bounce. Aggiungi un handler per questo evento.
Al posto della verifica dei messaggi SNS, firmiamo secondo la specifica Standard Webhooks, con header HMAC sulla consegna stessa. La procedura di verifica è in Webhook ed eventi.
Passaggio in produzione
Segui domini e DNS e lo smoke test in sandbox nella guida principale. Entrambi sono indipendenti dal provider. Una nota specifica per SES nel passaggio DNS: i CNAME DKIM di SES restano attivi durante la transizione. Il nostro record TXT DKIM usa un proprio selettore, quindi i due coesistono.
Passaggi 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: smoke test della nuova integrazione prima del passaggio in produzione
- Soppressioni: verifica la lista importata e come la manteniamo da qui in avanti
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