# Migrate from AgentMail to Bird

Move one agent inbox with its conversation and application state intact. Start with an address you control, then switch a customer cohort after receiving, replies and recovery work.

## Map the integration

| AgentMail integration                                                     | Bird implementation                                                                                                                                                            |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Inbox identity                                                            | Save the new `mbx_` mailbox ID against the same application owner. Retain the old inbox reference for history.                                                                 |
| Message reply using inbox and message IDs                                 | Use the Bird `thr_` thread ID and `rem_` received-message ID with `email.threads.messages.reply`. Save its outgoing `em_` ID.                                                  |
| `message.received` event with `event_type`, `event_id` and nested message | Parse Bird's `type: email_mailbox.message_received` and `data.mailbox_id`, `data.thread_id`, `data.message_id`. Verify the Bird webhook signature before reading those values. |
| Agent drafts or application approvals                                     | Keep the reviewed text and approval in your application; submit the approved reply through Bird. Inventory any native draft dependency before moving it.                       |
| Existing message archive                                                  | Keep provider-qualified references. This migration does not import old IDs or history into Bird threads.                                                                       |

Check the original [AgentMail message operations](https://docs.agentmail.to/messages) and [event shapes](https://docs.agentmail.to/events) when updating your adapter. Do not only rename the webhook event: its envelope and IDs also change.

## Change the retry policy deliberately

AgentMail documents `client_id` for resource creation and `Idempotency-Key` for sending, replies and forwards. Its send keys expire 24 hours after completion. See [AgentMail idempotency](https://docs.agentmail.to/idempotency).

Bird retains completed responses for three hours. A timeout can occur after a send takes effect but before its response is retained. Keep one stored operation ID for the intended reply and reconcile an uncertain outcome against its saved metadata and message record before sending again. Neither provider's key deduplicates a send performed by the other. Follow the [Bird idempotency protocol](/docs/guides/idempotency).

## Build the Bird workflow

Start with the complete [Node.js support inbox](/docs/get-started/quickstarts/typescript/mailboxes) or [Python support inbox](/docs/get-started/quickstarts/python/mailboxes). Each creates a mailbox, receives a message, records an application-owned support case and acknowledges it in the original thread. A later message updates that case; a repeated message does not send another acknowledgement.

The examples keep a small local checkpoint for development. Put the same case, incoming-message and outgoing-operation identities in your application's durable store before running multiple workers. Keep the business action separate from the email: acknowledging a refund request does not issue a refund.

Then add the [signed event receiver and attachment workflow](/docs/guides/mailboxes/events-and-attachments). Store the received-message ID with the case before acknowledging the event. Retrieve attachment metadata and bytes through the documented operations; keep any retained files under your application's access and retention rules.

## Test the switch

| Test                                               | Expected application result                                                    |
| -------------------------------------------------- | ------------------------------------------------------------------------------ |
| New inbound request and one attachment             | One case, correct attachment metadata, one reply tied to the source message.   |
| Same event delivered twice                         | The received-message ID resolves to the existing job.                          |
| Later customer reply                               | The case stays the same; the new message gets its own processing record.       |
| Customer replies while an answer is being prepared | Re-read the latest message before sending; review a stale answer.              |
| Send response is lost                              | Keep the operation uncertain; confirm the actual send before allowing another. |

Keep the old worker from processing the migrated cohort. During rollback, stop new Bird assignments first, reconcile already-started jobs and then restore routing. A routing change cannot retract a reply already sent.

## Next steps

- [Compare Bird and AgentMail](/products/mailboxes/compare/bird-vs-agentmail)
- [Mailbox integration and retention](/docs/guides/email/mailboxes)
- [Resolve receiving and reply problems](/docs/guides/mailboxes/troubleshooting)
- [All mailbox migration guides](/docs/guides/mailboxes/migrate)
- [Mailbox resources](/mailboxes/resources)
- [Email pricing](/products/email/pricing)

## Related resources

- [Getting started with email](/learn/email/getting-started-with-email) (video)
- [Email](/email-api) (product)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=email)