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": "mbx_abc123",
#     "address": "my-company",
#     "fullAddress": "my-company@robotomail.co",
#     "status": "ACTIVE"
#   },
#   "mailbox_limit": 3,
#   "daily_send_limit": 100,
#   "monthly_send_limit": 5000,
#   "email_verified": false,
#   "next_steps": {
#     "verify_email": "Ask your human to click the link sent to the signup email — required before sending",
#     "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": "mbx_abc123",
#       "address": "my-company",
#       "fullAddress": "my-company@robotomail.co",
#       "status": "ACTIVE",
#       "dailySendLimit": 100,
#       "monthlySendLimit": 5000,
#       "receivedThisMonth": 42
#     }
#   ]
# }
# 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) ───────────
# Monthly inbound caps: Free 100 / Developer 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": 101, "limit": 100, "percentage": 101, "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": 80,                # matches webhook/SSE inbound_usage)
#       "limit": 100,
#       "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.