Switching from AgentMail

MachineMail implements AgentMail’s /v0 API. Wherever AgentMail defines a path, a field name or an enum value, MachineMail uses the same one. Switching is a base URL and an API key.

The change

1. Get a MachineMail key

   Sign up at machinemail.dev/signup and copy the API key the dashboard shows after your first sign-in. Keys start with mm_live_. See the Quickstart.

2. Point your client at MachineMail

   TypeScript SDKPython SDKHTTP

   import { AgentMailClient } from 'agentmail';
   
   const mail = new AgentMailClient({
     apiKey: process.env.MACHINEMAIL_API_KEY,
     baseUrl: 'https://api.machinemail.dev', // the only change
   });
   
   const inbox = await mail.inboxes.create({ username: 'support-agent', displayName: 'Support agent' });
   await mail.inboxes.messages.send(inbox.inboxId, {
     to: ['ada@example.com'],
     subject: 'Hello',
     text: 'Sent through the AgentMail SDK, served by MachineMail.',
   });

   import os
   from agentmail import AgentMail
   
   mail = AgentMail(
       api_key=os.environ["MACHINEMAIL_API_KEY"],
       base_url="https://api.machinemail.dev",  # the only change
   )
   
   inbox = mail.inboxes.create(username="support-agent", display_name="Support agent")
   mail.inboxes.messages.send(
       inbox.inbox_id,
       to=["ada@example.com"],
       subject="Hello",
       text="Sent through the AgentMail SDK, served by MachineMail.",
   )

   # Before
   curl https://api.agentmail.to/v0/inboxes -H "Authorization: Bearer $AGENTMAIL_API_KEY"
   
   # After
   curl https://api.machinemail.dev/v0/inboxes -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

3. Update webhook verification

   MachineMail signs webhooks with its own X-MachineMail-Signature header. If you verify AgentMail webhooks with Svix, replace that check. See Verify webhook signatures.

4. Update your MCP config

   If your agent uses MCP, point it at https://mcp.machinemail.dev/mcp with the MachineMail key as a Bearer token. Tool names differ from AgentMail’s MCP server. See MCP server and MCP tools.

What carries over

What MachineMail adds

These are extra fields and endpoints. AgentMail clients ignore what they do not know, so they do not break anything.

• trust on every inbound message, plus trust_level on list items and GET /v0/inboxes/{inbox_id}/messages/{message_id}/trust. See Trust.
• A QUARANTINE label. Mail that tries to instruct your agent, or looks like phishing, gets QUARANTINE instead of INBOX and a message.received.quarantined event. Lists hide it unless you pass include_quarantine=true.
• Ephemeral inboxes with ttl_seconds, ephemeral and expires_at, and an inbox.expired event when they are deleted.
• Catch-all domains with catch_all, catch_all_ttl_seconds and inbound_enabled on domains, plus DNS host detection and Domain Connect. See Domains.
• Webhook delivery log: GET /v0/webhooks/{webhook_id}/deliveries, replay and test.
• An event log and SSE stream: GET /v0/events and GET /v0/events/stream.
• Suppressions at /v0/suppressions, filled automatically from bounces and complaints.
• Export at GET /v0/inboxes/{inbox_id}/export?format=mbox|jsonl.
• Agent self-registration through auth.md.

In the TypeScript SDK, extension fields come through untouched and in snake_case, so read them with a cast:

const message = await mail.inboxes.messages.get(inboxId, messageId);
const trust = (message as any).trust; // { level, score, content: { text }, reasons, ... }
if (trust?.level === 'quarantined') return;

What is different

Not available yet

These AgentMail endpoints return 404 on MachineMail:

• Apps and accounts (/v0/apps, /v0/accounts and the inbox and pod variants)
• Calendar (/v0/inboxes/{inbox_id}/calendar/...)
• Custom webhook headers (.../webhooks/{webhook_id}/headers)
• Hosted domain setup links (/v0/domains/{domain_id}/setup-link)
• POST /v0/inboxes/{inbox_id}/authorize
• Attachment downloads through threads and drafts (/threads/{thread_id}/attachments/{attachment_id}, /drafts/{draft_id}/attachments/{attachment_id}). Fetch attachments through the message instead.

The AgentMail compatibility reference lists every operation.

Moving existing mail

There is no importer. Your AgentMail data, and addresses on AgentMail’s own domain, stay with AgentMail. A practical migration:

1. Create the new inboxes on MachineMail, on machinemail.dev or on your own domain.
2. If you use a custom domain, add it to MachineMail and switch its MX, SPF and DKIM records to the ones MachineMail gives you. See Set up a custom domain.
3. Recreate your webhooks. Each gets a new secret.
4. Keep the old AgentMail inboxes readable until in-flight threads are finished.

Next