Skip to content

Agents

An agent with its own addresses

An agent key creates addresses in a workspace, reads their mail through one list, and sends from them.

An agent works inside one Business workspace. Its key has agent_access, one or more scopes (create, read, send), and optionally a subset of the workspace's domains. An address the agent creates is attached to the person who authorized the key, carries the agent icon in Mail and Accounts, and is disabled as a human sign-in. It still receives mail, and the agent reads and sends it through these endpoints. Agent sends count as API sends: on Flex they use the 500 monthly sends and then prepaid 1,000-send blocks; on the other plans they use the plan's monthly API send allowance. They never take the mailbox per-minute throttle.

Authorize

Open https://accounts.chebu.io/agent/authorize with workspace_id, name, scopes, domains, redirect_uri and state. A signed-in owner or admin approves it. With a redirect_uri, the page sends code and state there; without one, it shows the key once.

POST/agent/token
Request
curl -X POST https://api.chebu.io/agent/token \
  -H "Authorization: Bearer $CHEBU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "…", "code_verifier": "…" }'
JSON

Workspaces and domains

GET/agent/workspaces
Request
curl https://api.chebu.io/agent/workspaces \
  -H "Authorization: Bearer $CHEBU_API_KEY"
JSON

GET /agent/domains returns the same domains as one flat list.

Create an address

POST/agent/identities
Request
curl -X POST https://api.chebu.io/agent/identities \
  -H "Authorization: Bearer $CHEBU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "d91cd9bd-1176-453e-8fc1-35364d380206",
    "name": "Receipts agent"
  }'
JSON

Without local_part, the name is 24 random base62 characters; the server checks the domain and retries on a collision. A requested local_part is refused when it is already taken.

Read mail: one endpoint, one filter

GET /agent/emails returns summaries, never bodies. filter is all (default: inbox and sent, not archived, trash or spam), read, unread, spam, sent, archive or trash. Each row says where the message belongs: read, unread, archived, trashed, spam, sent, starred.

GET/agent/emails
Request
curl https://api.chebu.io/agent/emails?filter=unread \
  -H "Authorization: Bearer $CHEBU_API_KEY"
JSON

GET /agent/emails/{mid} returns the message body with its attachments and marks it read. Attachments download from /agent/emails/{mid}/attachments/{index} with the same key.

Send

POST/agent/emails
Request
curl -X POST https://api.chebu.io/agent/emails \
  -H "Authorization: Bearer $CHEBU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "acct_…",
    "to": ["maya@example.com"],
    "subject": "Your receipt #1042",
    "text": "Thanks for your order."
  }'
JSON

Use identity_id, or from with an address the key created. Sending from a person's address is refused. The agent key cannot call the Resend-compatible API; its mail surface is the /agent paths.