Migrate Nylas Agent Accounts to Bird Mailboxes

Nylas supports both hosted Agent Account mailboxes and connected user accounts. This guide moves an agent-owned inbox to Bird; retain connected-account access for features that still read a user’s existing mailbox.

An Agent Account uses a grant_id and the /v3/grants/{grant_id} API surface. Inventory the actual message, thread, folder, draft and attachment operations your application uses. See Nylas Agent Account mailboxes and supported endpoints.

Keep the application case ID stable across the move. For new Bird mail, save the mailbox and thread IDs with that case. For older conversations, keep an archive link or provider-qualified reference accessible to the support team. Do not derive conversation identity from the subject alone.

Test two unrelated messages with identical subjects, a reply to the first message and a forwarded message. Verify which conversation each belongs to in the actual returned thread. Use Nylas threading guidance to identify behavior your previous adapter relied on.

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.

Confirm the address customers will use and the return address on a real reply. A new mailbox does not automatically move your existing domain, grant or historical messages.

Run one worker owner per customer task during the switch. Test a repeated event, a new reply while the worker is busy and a lost send response. Record the resulting incoming ID, case ID and outgoing ID, then inspect the recipient's actual conversation.

Reconcile outstanding Nylas jobs before disabling their consumer. Keep the prior archive and any still-needed connected-account integration available. If the new path fails, pause new Bird assignments and resolve in-flight operations before restoring the old route.