Agent Mail API

Base URL https://app.cloudbox.biz. Authenticate with your CloudBox API key: Authorization: Bearer cbs_.... Write actions need a key with the write scope.

Inboxes

Create an inbox. Body: {"name": "billing-bot", "domain": "agents.cloudbox.biz"} (both optional).

Update display_name, mode (open|allowlist|blocklist), allow_list/block_list (newline-separated addresses or @domain), retention_days, or status.

Messages

Query: limit (≤100), before, q, unread=1, direction=in|out.

Long-poll - see Webhooks & waiting.

Body: to (string or array), cc, bcc, subject, text, html. Send an Idempotency-Key header to make retries safe.

Body: text, html, all (reply-all). Threading headers are set for you.

Threads & usage

Returns this month's inbox count, message counts and your plan caps.

A message object

{
  "message_id": "msg_9f2c...",
  "thread_key": "msg_9f2c...",
  "direction": "in",
  "from": "ap@acme.com",
  "to": ["billing-bot@agents.cloudbox.biz"],
  "subject": "Invoice 4821",
  "snippet": "Please find attached...",
  "text": "Please find attached...",
  "attachments": [{"filename": "invoice.pdf", "size": 48213, "content_type": "application/pdf"}],
  "is_read": false,
  "created": "2026-08-02T10:14:00Z"
}