Migrate from AgentMail to Robotomail: Worked Example

12 min read

Move one agent inbox workflow from AgentMail to Robotomail: map operations, port an adapter, test replies and webhooks, then stage rollout and rollback.

John Joubert

John Joubert

Founder, Robotomail

Migrate from AgentMail to Robotomail: Worked Example
Table of contents

Moving an agent platform from AgentMail to Robotomail is an adapter migration. You put both providers behind one interface in your own code, port one representative inbox workflow, prove it against written acceptance criteria, and then move customers in small cohorts with a rollback path. You can keep addresses on domains you control. Addresses on AgentMail's own domain cannot come with you. Historical mail does not transfer automatically, so plan that separately.

This post works through that process with a fictional platform called RelayDesk. RelayDesk is an illustration, not a customer case study. All names, IDs and example.com addresses are made up. For a feature-level purchasing comparison, see Robotomail vs AgentMail. This post assumes you are past that stage and want to know what the switch actually involves.

Define the workflow before you choose

Start with one workflow your platform runs every day, and write it down as a sequence of operations. Do not start from a feature list. RelayDesk's enquiry agent does this:

  1. Provision an inbox for a customer's enquiry agent.
  2. Send an enquiry follow-up to a prospect.
  3. Receive the prospect's reply as an event.
  4. Fetch the full message and its thread.
  5. Resume the correct customer's agent with that context, and send a threaded reply.

Then list the AgentMail features your code actually calls today. Use your codebase as the source, not AgentMail's docs. If you use custom domains, Svix-verified webhooks and the reply endpoint, those three are your must-haves. If you never touched some capability, leave it off the list. Do not assume that unused functionality has a direct equivalent, and do not let it block the decision.

RelayDesk's pilot scope is one test customer and one enquiry agent. Everything below is sized to that.

Map the operations, not the products

AgentMail supports sending, receiving, replies, events and custom domains. Robotomail covers the same workflow with different shapes. Here is how the RelayDesk path maps, based on each provider's official Python documentation:

Step AgentMail (Python) Robotomail (Python SDK)
Provision client.inboxes.create() create_mailbox(body)
Send client.inboxes.messages.send(inbox_id, ..., text=...) send_message(mailbox_id, {"to", "subject", "bodyText"})
Read inbound event payload, then message fetch get_message(mailbox_id, message_id)
Reply client.inboxes.messages.reply(inbox_id=..., message_id=..., text=...) send_message(...) with inReplyTo set to the fetched RFC messageId
Webhook auth Svix headers HMAC-SHA256 in X-Robotomail-Signature

The biggest difference is how replies work. AgentMail has a dedicated reply operation keyed by its message ID. Robotomail replies are ordinary sends that carry the original message's RFC 5322 Message-ID in inReplyTo.

Provider IDs are not interchangeable. An AgentMail inbox ID is not a Robotomail mailbox ID, and a thread ID from one provider means nothing to the other. Do not substitute one for the other. Store an explicit mapping instead.

The mapping RelayDesk owns

This schema is application-owned. It is RelayDesk's code, not a Robotomail feature:

-- Application-owned mapping (RelayDesk). Not part of either provider.
create table agent_mailboxes (
  customer_id         text not null,
  agent_id            text not null,
  provider            text not null,   -- 'agentmail' or 'robotomail'
  provider_mailbox_id text not null,
  address             text not null,
  active_sender       boolean not null default false,
  primary key (provider, provider_mailbox_id)
);

create table thread_map (
  customer_id        text not null,
  agent_id           text not null,
  provider           text not null,
  provider_thread_id text not null,
  primary key (provider, provider_thread_id)
);

Your customer IDs and agent IDs stay the same. Only the provider columns change. The active_sender flag is how you guarantee that exactly one provider sends for a given customer at any moment.

Port one adapter path to Robotomail

Install the official Python SDK (Python 3.10+). Keep ROBOTOMAIL_API_KEY on the server and never in agent prompts or client code. Setup details are in the Python SDK docs.

pip install "robotomail @ git+https://github.com/robotomail/robotomail-python.git@v0.1.0"

The SDK returns dictionaries. API responses use camelCase. Webhook data fields use snake_case, so keep that split in mind when you write accessors.

Provision and send

# Application-owned adapter. `rm` is the Robotomail SDK client, constructed
# with ROBOTOMAIL_API_KEY as shown in the Python SDK docs.

def provision(customer_id: str, agent_id: str, local_part: str) -> None:
    created = rm.create_mailbox({"address": local_part})
    # Read the mailbox id and address from the response as documented in
    # the Mailboxes API reference, then record the mapping.
    store.add_mailbox(customer_id, agent_id, provider="robotomail",
                      response=created, active_sender=False)

def send_followup(route, to_addr: str, subject: str, body: str):
    if not route.active_sender:
        raise RuntimeError("robotomail is not the active sender for this customer")
    return rm.send_message(route.provider_mailbox_id, {
        "to": [to_addr],
        "subject": subject,
        "bodyText": body,
    })

For a mailbox on a custom domain, the create body also takes domainId, which must be that domain's UUID. Leave it out for platform-domain mailboxes.

A successful send call means Robotomail accepted the message. It does not mean the message was delivered. Track delivery outcomes separately through the events described in the Events API reference.

Two webhook verifiers, not one

Do not reuse your AgentMail verifier, and do not assume the two event envelopes match.

  • AgentMail: its webhook verification docs describe Svix headers (svix-id, svix-timestamp, svix-signature). They recommend the payload's event_id for deduplication across endpoints.
  • Robotomail: it signs the raw request body with HMAC-SHA256 and sends the signature in X-Robotomail-Signature. Retries carry a stable X-Robotomail-Delivery-Id, which is your dedupe key. The envelope is { event, timestamp, data }.

Keep a separate endpoint and secret for each provider during the transition.

# Application-owned handler (framework-agnostic sketch).
import hashlib, hmac, json, os

SECRET = os.environ["ROBOTOMAIL_WEBHOOK_SECRET"].encode()

def handle_robotomail(raw_body: bytes, headers: dict) -> int:
    # Verify against the raw bytes, before any JSON parsing.
    # Confirm the exact signature encoding in the webhooks docs before shipping.
    expected = hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, headers.get("x-robotomail-signature", "")):
        return 401

    delivery_id = headers.get("x-robotomail-delivery-id")
    if store.delivery_seen(delivery_id):
        return 200  # a retry we already handled

    event = json.loads(raw_body)
    if event["event"] == "message.received":
        data = event["data"]
        route = store.route_for("robotomail", data["mailbox_id"])
        if route is None:
            reconcile.put(data)  # unknown ownership: human review, never guess
        else:
            jobs.enqueue(resume_agent, route, data)

    store.mark_delivery(delivery_id)
    return 200

Normalize header case the way your framework requires.

Fetch, resume and reply

The webhook gives you message_id (the stored message UUID), mailbox_id and thread_id. To reply, fetch the full message and use its RFC Message-ID:

# Application-owned. The agent/model call is yours; Robotomail only moves mail.

def resume_agent(route, data: dict) -> None:
    msg = rm.get_message(data["mailbox_id"], data["message_id"])["message"]

    if not msg.get("messageId"):
        reconcile.put(data)  # no RFC Message-ID: do not invent reply headers
        return

    store.upsert_thread(route.customer_id, route.agent_id,
                        provider="robotomail", provider_thread_id=msg["threadId"])

    reply_text = agents.run(route.agent_id, msg)  # your model, your rules
    rm.send_message(msg["mailboxId"], {
        "to": [msg["fromAddress"]],
        "subject": reply_subject(msg["subject"]),
        "bodyText": reply_text,
        "inReplyTo": msg["messageId"],  # RFC Message-ID, never the UUID
    })

Never put the stored message UUID or the thread UUID in inReplyTo. If the agent needs earlier context, read the thread at GET /v1/mailboxes/{mailboxId}/threads/{threadId}.

Acceptance tests for the pilot

Write these down before the pilot starts. Each one should pass on the test customer before any real customer moves:

  1. Send: the follow-up is accepted. Delivery is confirmed separately through events, not inferred from the send call.
  2. Receive: a reply from an external test address produces one message.received event that routes to the right agent.
  3. Threading: the agent's reply shows up in the prospect's mail client as part of the same conversation.
  4. Duplicate event: replay the same delivery. The agent runs once.
  5. Revoked key: revoke the API key mid-test. Sends fail loudly, alerts fire, and nothing retries in a tight loop.
  6. Quota failure: drive a mailbox to a limit, or simulate the documented error. The adapter surfaces it and does not drop the message silently. The Errors reference lists the shapes.
  7. No wrong-customer routing: send to two pilot mailboxes at once. Each reply lands with its own customer, and an unmapped mailbox goes to reconciliation.

Run the pilot long enough to see real reply patterns. We are not going to promise you speed or cost numbers. Measure your own workflow and judge fit from what you observe.

Address continuity vs history: AgentMail to Robotomail

People often treat these as one question. They are two separate questions.

Can we keep the same addresses?

  • Address on AgentMail's own domain: no. That domain belongs to AgentMail, and you cannot recreate it in Robotomail. Those addresses change, so tell correspondents the new address.
  • Address on a domain you control: yes, with deliberate work. Add the domain in Robotomail and publish the DNS records it returns. Provision a mailbox with the same local part. Then change inbound MX when you are ready to cut over. The custom domain guide walks through the records. AgentMail's custom domain docs describe its side.
  • Dedicated subdomain (for example agents.example.com): this avoids conflicts with staff email on the root domain, but the address changes.

Verifying a domain proves you control it. It does not transfer any mailbox content.

What happens to old mail?

You have to rebuild some things and keep others.

Rebuild: Robotomail mailbox IDs, API keys, webhook endpoints and secrets, and provider-specific thread mappings.

Keep, with adapter changes: your customer records, agent IDs, business rules and permissions. Robotomail supplies email infrastructure. It does not supply your model, scheduler, customer database, billing or application permissions.

For history, we did not find a bulk mailbox or message import, or a built-in AgentMail migration feature, in Robotomail's public API. Do not try to "import" old mail by replaying it through send_message. That sends real email to real people.

Instead, read the history out of AgentMail with its official message, list and raw-message APIs, where your account has access to them. AgentMail's get-raw endpoint returns a signed download_url with an expires_at, so download promptly. Store the result in your own archive under your retention policy.

Robotomail threads will not contain old AgentMail conversations. Route late replies to old threads explicitly: either keep AgentMail access during the transition, or answer from your archive with a human in the loop.

Staged rollout and rollback

  1. Pilot on a separate test address or subdomain, with the test customer only.
  2. Gate per customer: active_sender decides which provider sends. Only one provider is active per customer.
  3. Switch a small cohort, then watch the acceptance checks in production.
  4. Keep the old side running: retain AgentMail credentials, receiving and webhooks for in-flight conversations and while DNS propagates.
  5. One responder per enquiry: if a reply arrives at both providers during an MX change, only the active sender's agent answers. Two autoresponders replying to one prospect is the classic migration bug.

Rollback means flipping active_sender back and, if you changed MX, reverting DNS with propagation time in mind. Rollback does not copy mail that arrived at Robotomail back into AgentMail. Your archive needs to cover that window as well.

Before you delete anything old, confirm:

  • No inbound mail has reached AgentMail inboxes for an agreed quiet period.
  • Every customer in the cohort has passed the acceptance tests.
  • History is exported and readable from your archive.
  • Old webhook endpoints are receiving no traffic.
  • The rollback steps are documented and have been rehearsed once.

Check plan capacity before committing

Count every mailbox, including the signup mailbox and any test or operations mailboxes.

Suppose RelayDesk serves ten customers with two agent mailboxes each. That is 20 mailboxes, plus one signup and one test mailbox. Starter allows 10 mailboxes, so it does not fit. Growth allows 50 mailboxes, which covers the count, but only if its other limits also fit:

  • 1,000 sends per day per mailbox
  • 20,000 inbound messages per month shared across the account
  • Five custom domains. If each customer brings its own domain, ten domains exceeds that.

Also include storage, model costs and hosting costs in the estimate. A mailbox is not an unlimited tenant. These numbers are capacity examples, not cost guarantees, and current terms are on pricing.

Until you pay, an account is restricted. It can exchange mail only with the verified owner address, up to 10 sends and 10 receives per calendar month. External correspondence and custom domains require a paid plan. A single-mailbox pilot fits Solo, the entry plan.

FAQ

Is there a one-click AgentMail import?

No. We found no documented bulk import or AgentMail migration feature. Export history through AgentMail's APIs into your own archive, and provision new mailboxes in Robotomail.

Can I reuse my AgentMail webhook verifier?

No. AgentMail uses Svix headers and event_id. Robotomail uses raw-body HMAC-SHA256 in X-Robotomail-Signature and deduplicates with X-Robotomail-Delivery-Id. Write a separate verifier for each.

What goes in inReplyTo?

Put the RFC Message-ID from the fetched message's messageId field. Never use the stored message UUID or the thread UUID. If the Message-ID is missing, send the message to reconciliation.

Should we switch if AgentMail already works?

Only if the pilot passes your acceptance tests and the plan fits your capacity. Start with the comparison page, and check the broader options if you are still deciding which providers to evaluate.

To evaluate this for your platform, create one pilot mailbox, run the acceptance checklist above, and decide on a wider migration based on what you measure. More at Robotomail.

Give your AI agent a real email address

Create a mailbox, connect your agent and test a conversation. Send, receive and retrieve the thread through one API.

Related posts