Set up your email

POST /v1/signup
Content-Type: application/json

{
  "email": "you@company.com",
  "password": "a-secure-password",
  "slug": "my-company"
}

# Response (201):
# {
#   "user": { "slug": "my-company", "platform_email": "my-company@robotomail.co" },
#   "api_key": { "key": "rm_a1b2c3d4..." },
#   "mailbox": {
#     "id": "b3a2c801-7d9f-4e1a-8c52-1f0a9d3e4b6c",
#     "address": "my-company",
#     "fullAddress": "my-company@robotomail.co",
#     "status": "ACTIVE"
#   },
#   "mailbox_limit": 1,
#   "daily_send_limit": 10,
#   "monthly_send_limit": 10,
#   "email_verified": false,
#   "next_steps": {
#     "verify_email": "Ask your human to click the link sent to the signup email. Required before the API key works.",
#     "add_payment": "1 mailbox, 10 sends and 10 receives per month. Exchange mail only between your agent and your verified email address. Upgrade to email anyone. No credit card, no expiry. Allowances reset on the first of each month (UTC). Upgrade for higher limits or a custom domain. Optional: POST /v1/billing/upgrade returns a checkout URL for your human to review.",
#     "add_domain": "POST /v1/domains",
#     "send_email": "POST /v1/mailboxes/:id/messages"
#   }
# }
#
# Header: X-RateLimit-Remaining: <number>

GET /v1/mailboxes
Authorization: Bearer rm_a1b2c3d4...

# Response (200):
# {
#   "mailboxes": [
#     {
#       "id": "b3a2c801-7d9f-4e1a-8c52-1f0a9d3e4b6c",
#       "address": "my-company",
#       "fullAddress": "my-company@robotomail.co",
#       "status": "ACTIVE",
#       "dailySendLimit": 10,
#       "monthlySendLimit": 10,
#       "receivedThisMonth": 4
#     }
#   ]
# }
# receivedThisMonth is the per-mailbox inbound count for the current
# calendar month (UTC). The account-level cap is the sum across mailboxes.

# Set a display name (emails will show "Hal" <my-company@robotomail.co>):
PATCH /v1/mailboxes/:id
Authorization: Bearer rm_a1b2c3d4...
Content-Type: application/json

{
  "displayName": "Hal"
}

POST /v1/mailboxes/:id/messages
Authorization: Bearer rm_a1b2c3d4...
Content-Type: application/json

{
  "to": ["recipient@example.com"],
  "subject": "Hello from my agent",
  "bodyText": "This is the email body."
}

# Option A: Webhooks (real-time push)
POST /v1/webhooks
Authorization: Bearer rm_a1b2c3d4...
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": ["message.received"],
  "headers": {
    "Authorization": "Bearer your-token"
  }
}

# Response (201):
# {
#   "webhook": {
#     "id": "wh_abc123",
#     "url": "https://your-server.com/webhook",
#     "events": ["message.received"],
#     "secret": "a1b2c3d4e5f6..."
#   }
# }
# Save the secret — it is only returned on creation.

# Option B: SSE (real-time stream — no public URL needed)
# Use the CLI: robotomail listen --forward-to http://localhost:4000/hook
# Or connect directly:
GET /v1/events?events=message.received
Authorization: Bearer rm_a1b2c3d4...
Accept: text/event-stream
# Events stream as Server-Sent Events. Reconnect with Last-Event-ID
# to replay missed events. See docs for all 5 event types.

# Option C: Polling (simplest for batch processing)
GET /v1/mailboxes/:id/messages?direction=INBOUND&since=2026-03-11T00:00:00Z&limit=10
Authorization: Bearer rm_a1b2c3d4...

# Poll every 10-30 seconds. Use direction=INBOUND and since
# with an ISO timestamp to get new inbound messages.
# Track the latest createdAt to avoid reprocessing.

# ─── Inbound attachments ────────────────────────────────────────
# Webhook/SSE message.received payload shape:
# {
#   "event": "message.received",
#   "timestamp": "2026-03-18T12:00:00.000Z",
#   "data": {
#     "message_id": "...",
#     "from": "...",
#     "body_html": "<img src=\"cid:logo@acme\" />...",
#     "attachments": [
#       {
#         "id": "att_...",
#         "filename": "invoice.pdf",
#         "content_type": "application/pdf",
#         "size_bytes": 204800,
#         "content_id": null,
#         "download_url": "https://...r2.cloudflarestorage.com/...?signed-24h"
#       }
#     ]
#   }
# }
#
# Fetch each attachment with HTTP GET on download_url — no auth header needed.
# For inline images (content_id != null), rewrite cid:<content_id> in body_html
# to download_url before passing the HTML to a renderer.
#
# REST list/get does NOT include download_url — call GET /v1/attachments/:id
# to fetch a fresh presigned URL (also use this if a download_url has expired).
#
# Drop limits: max 20 attachments per message, 25 MB each. If exceeded,
# attachments_dropped: true and attachments_dropped_reason: "size"|"count"|"both".
#
# ─── Quota-gated payloads (over monthly inbound limit) ───────────
# Paid monthly inbound caps: Solo 500 / Starter 2,000 / Growth 20,000 /
# Scale unlimited. When your account is over its cap, every subsequent
# inbound message still fires a message.received event — but the data
# object drops to a stub (identity fields only, no body/attachments):
# {
#   "event": "message.received",
#   "timestamp": "2026-03-18T12:00:00.000Z",
#   "data": {
#     "over_limit": true,
#     "message_id": "...",
#     "mailbox_id": "...",
#     "mailbox_address": "...",
#     "received_at": "...",
#     "account": {
#       "inbound_usage": { "current": 2001, "limit": 2000, "percentage": 100, "reset_date": "2026-05-01T00:00:00.000Z", "status": "limit_reached" },
#       "upgrade": { "browser_url": "https://robotomail.com/billing", "api_endpoint": {"method":"POST","path":"/v1/billing/upgrade"}, "hint": "..." }
#     }
#   }
# }
# Branch on data.over_limit === true. Stubs carry NO from/to/subject/body/attachments.
#
# While over-limit: GET /v1/mailboxes/:id/messages/:msgId and
# GET /v1/attachments/:id return 402 INBOUND_LIMIT_EXCEEDED until
# you upgrade or the monthly reset lands. List endpoints
# (GET /v1/mailboxes/:id/messages, /threads) still return 200 —
# they hide over-limit messages and expose the count at
# metadata.overLimitCount. Upgrade with POST /v1/billing/upgrade;
# previously gated messages become readable via the list endpoint.
# They are NOT retroactively redelivered via webhook/SSE.
#
# List envelope metadata (GET messages / GET threads):
# {
#   "metadata": {
#     "overLimitCount": 3,
#     "upgrade": {                    # always present (camelCase)
#       "browserUrl": "https://robotomail.com/billing",
#       "apiEndpoint": {"method":"POST","path":"/v1/billing/upgrade"},
#       "hint": "..."
#     },
#     "limitHint": {                  # present once usage ≥ 50 % (snake_case,
#       "current": 1600,                # matches webhook/SSE inbound_usage)
#       "limit": 2000,
#       "percentage": 80,
#       "reset_date": "2026-05-01T00:00:00.000Z",
#       "status": "near"              # approaching | near | limit_reached
#     }
#   }
# }
#
# Approaching the limit (≥ 50 %): full payloads carry a
# data.account.inbound_usage block (no upgrade sub-field yet).
# Use it to surface a countdown.