Inboxes

An inbox is a real address that an agent can receive, inspect, organise and answer over the API. Each inbox belongs to a tenant and has its own threads, folders, messages, attachments, drafts and outbound policy.

Lifecycle

Create:

{
  "domain_id": "DOMAIN_ID",
  "local_part": "support",
  "display_name": "Support Agent",
  "policy": {
    "dlp": "enforce",
    "max_send_per_hour": 100,
    "allow_recipients": ["customer.example"],
    "require_approval_on_taint": true
  },
  "metadata": {"purpose": "customer-support"}
}

status is active or paused; a paused inbox refuses compose operations with 409 inbox_paused. provider is native or, for connected mailboxes, google / microsoft.

Lists are newest first; pass the last item’s created_at as cursor for the next page. limit defaults to 50, max 200.

Reading mail

GET /v1/inboxes/{id}/messages

A message:

{
  "id": "MESSAGE_ID",
  "inbox_id": "INBOX_ID",
  "thread_id": "THREAD_ID",
  "direction": "in",
  "from": "customer@example.net",
  "to": ["support@agents.example.com"],
  "subject": "I need help",
  "snippet": "I need help with...",
  "text": "I need help with my order.",
  "extracted_text": "I need help with my order.",
  "verdict": "clean",
  "auth": {"spf": "pass", "dkim": "pass", "dmarc": "pass"},
  "shield": {},
  "labels": [],
  "folder": "inbox",
  "read": false,
  "has_html": false,
  "attachments": [{"id": "ATT_ID", "filename": "receipt.pdf", "content_type": "application/pdf", "size": 48213}],
  "created_at": "2026-10-03T18:01:00Z"
}

extracted_text includes text pulled from attachments where possible, so a model can read a PDF invoice without a separate parsing step.

Verdicts

Every inbound message gets a Shield verdict: clean, suspicious, spam, blocked or unauthenticated. spam and blocked land in the spam folder automatically. The verdict is a safety signal, not permission: anything other than clean should be treated as untrusted data, and no verdict means the message’s instructions should be executed.

Threads, search, raw content

Send, reply and forward

The inbox address is always the From; clients cannot override it. Outbound mail uses the same quotas, suppressions, DKIM and retries as relay sends, plus the inbox’s Shield policy.

Body (all three):

{
  "to": ["human@example.net"],
  "cc": [], "bcc": [],
  "subject": "Follow-up",
  "text": "Thanks for the details.",
  "html": "<p>Thanks for the details.</p>",
  "reply_all": false,
  "attachments": [{"filename": "details.pdf", "content_type": "application/pdf", "content": "<base64>", "content_id": "details", "inline": false}],
  "send_at": "2026-10-05T09:00:00Z"
}

At least one of text/html and one recipient. Attachments total ≤ 25 MiB. Replies default to the original sender and a Re: subject; forwards derive Fwd:.

Responses (all 202):

{ "message_id": "OUT_ID", "queued": 1, "thread_id": "THREAD_ID", "inbox_message_id": "SENT_COPY_ID" }

{ "held": true, "approval_id": "APPROVAL_ID", "reason": "dlp" }

{ "scheduled": true, "draft_id": "DRAFT_ID", "scheduled_at": "2026-10-05T09:00:00Z" }

Folders, moving, labels

System folders: inbox, sent, drafts, archive, spam, trash. Up to 100 custom folders (1–64 chars, case-insensitively unique, no /, \ or control characters).

Nothing can be moved into sent or drafts. Unread mail in spam/trash does not count toward thread unread totals.

Drafts and scheduled send

Drafts live in drafts. Sending one removes it and creates the sent copy (or an approval if policy requires review). Scheduled drafts are sent by the server at send_at, through the same policy.

Events: message.draft_saved, message.scheduled, message.draft_sent.

AI auto-label and extraction

When AI is enabled on the account (PATCH /v1/account, ai_enabled), inbound mail can be auto-labelled and structured data extracted on demand:

curl -X POST "$API/v1/inbox-messages/$MESSAGE_ID/extract" \
  -H "Authorization: Bearer $AGENT_KEY" -H "Content-Type: application/json" \
  -d '{"schema": {"type":"object","required":["order_id"],"properties":{"order_id":{"type":"string"}},"additionalProperties":false}, "save": true}'

Message content is treated as untrusted data; model output is returned to you and cannot trigger actions. Available from the Developer plan with a monthly token cap (100k on Developer, 1M on Startup). Auto-enrichment emits message.enriched. The same capability is exposed as the extract_data MCP tool.

Connected Gmail and Microsoft 365

An inbox can be backed by a real Gmail or Microsoft 365 mailbox instead of the native store, so an agent works an existing human mailbox with the same API, folders, search, streams, Shield and IMAP access.

OAuth tokens are sealed with the account’s data key. Connected mailboxes are available on Startup and Enterprise plans.