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 and event shapes 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.

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.

Build the Bird workflow

Start with the complete Node.js support inbox or Python support inbox. 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. 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.

Migrate from AgentMail to Bird

Map the integration

Change the retry policy deliberately

Build the Bird workflow

Test the switch

Next steps

Verwandte Ressourcen