MultiMail — Email-as-a-Service for AI Agents

MultiMail gives AI agents real email addresses. Agents send and receive markdown — we handle conversion to/from HTML email, delivery, and human oversight.

Base URL: https://api.multimail.dev

Auth: Bearer token (API key returned at signup)

Content-Type: application/json

Quick Start

1. Sign up

POST /v1/signup
{
  "operator_name": "Your Company",
  "payment_method": "stripe",
  "accepted_tos": true,
  "accepted_operator_agreement": true,
  "oversight_email": "human@yourcompany.com"
}

Returns:

{
  "tenant_id": "01JXYZ...",
  "api_key": "mm_live_...",     // Save this — shown only once
  "default_mailbox": "agent@yourslug.multimail.dev",
  "billing_url": "/v1/billing/checkout",
  "oversight_mode": "monitored",
  "message": "Tenant created. Complete billing to activate."
}

2. Activate billing

POST /v1/billing/checkout
Authorization: Bearer mm_live_...
{
  "plan": "starter"    // starter | growth | scale
}

Returns a checkout URL. Complete payment to activate sending.

3. Send an email

POST /v1/mailboxes/{mailbox_id}/send
Authorization: Bearer mm_live_...
{
  "to": ["recipient@example.com"],
  "subject": "Hello from my agent",
  "markdown": "## Update\n\nAll tasks completed successfully."
}

4. Read your inbox

GET /v1/mailboxes/{mailbox_id}/emails
Authorization: Bearer mm_live_...

Returns emails with markdown bodies, thread IDs, and attachment metadata.

5. Reply to a thread

POST /v1/mailboxes/{mailbox_id}/emails/{email_id}/reply
Authorization: Bearer mm_live_...
{
  "markdown": "Thanks for the update. I'll follow up tomorrow."
}

Key Concepts

Markdown-native

You send markdown, recipients get formatted HTML email. Inbound HTML is converted to markdown before you see it. You never deal with MIME, HTML, or raw email headers.

Oversight Modes

Every mailbox has an oversight mode controlling human involvement:

• autonomous — full send/receive, no approval needed
• monitored (default) — agent operates freely, all emails mirrored to oversight address
• gated_send — outbound requires human approval before delivery
• gated_all — both inbound and outbound require approval

Webhooks

Set a webhook_url on your mailbox to receive POST notifications when new email arrives. Alternatively, poll the inbox endpoint.

API Reference

Full OpenAPI spec: GET /v1/openapi.json

Endpoints

• POST /v1/signup — create tenant + get API key
• POST /v1/billing/checkout — Stripe checkout session
• POST /v1/billing/crypto-checkout — crypto payment
• POST /v1/mailboxes — create additional mailbox
• GET /v1/mailboxes — list mailboxes
• POST /v1/mailboxes/:id/send — send email (markdown)
• GET /v1/mailboxes/:id/emails — list inbox
• GET /v1/mailboxes/:id/emails/:eid — get single email
• POST /v1/mailboxes/:id/emails/:eid/reply — reply in-thread
• PATCH /v1/mailboxes/:id/emails/:eid — update email status
• POST /v1/oversight/decide — approve/reject gated email
• GET /v1/usage — usage stats

Authentication

All endpoints (except signup and webhooks) require a Bearer token:

Authorization: Bearer mm_live_...

API keys have scopes: read, send, admin, oversight. The key returned at signup has all scopes.

---

Questions? Email support@multimail.dev