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.
/agent/tokencurl -X POST https://api.chebu.io/agent/token \
-H "Authorization: Bearer $CHEBU_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "code": "…", "code_verifier": "…" }'{
"object": "api_key",
"id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
"token": "ck_Ab12Cd34_9f8e7d6c5b4a39281706f5e4d3c2b1a0",
"workspace_id": "ws_…",
"scopes": ["create", "read", "send"]
}Workspaces and domains
/agent/workspacescurl https://api.chebu.io/agent/workspaces \
-H "Authorization: Bearer $CHEBU_API_KEY"{
"object": "list",
"data": [
{
"id": "ws_…",
"name": "Northwind",
"kind": "BUSINESS",
"plan_code": "professional",
"domains": [
{
"id": "d91cd9bd-1176-453e-8fc1-35364d380206",
"name": "northwind.studio",
"workspace_id": "ws_…",
"ownership": "verified",
"can_create": true
}
]
}
]
}GET /agent/domains returns the same domains as one flat list.
Create an address
/agent/identitiescurl -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"
}'{
"object": "identity",
"id": "acct_…",
"address": "q7m2…@northwind.studio",
"name": "Receipts agent",
"domain_id": "d91cd9bd-1176-453e-8fc1-35364d380206",
"agent": true,
"status": "disabled",
"created_at": "2026-11-08T10:00:00Z"
}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.
/agent/emailscurl https://api.chebu.io/agent/emails?filter=unread \
-H "Authorization: Bearer $CHEBU_API_KEY"{
"object": "list",
"filter": "unread",
"data": [
{
"mid": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
"identity_id": "acct_…",
"identity_address": "q7m2…@northwind.studio",
"from": "maya@example.com",
"to": ["q7m2…@northwind.studio"],
"subject": "Your receipt #1042",
"snippet": "Thanks for your order.",
"received_at": "2026-11-08T10:04:12.418Z",
"flags": [],
"read": false,
"unread": true,
"archived": false,
"trashed": false,
"spam": false,
"sent": false,
"starred": false,
"has_attachment": false
}
],
"next_cursor": null
}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
/agent/emailscurl -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."
}'{
"object": "email",
"mid": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
"accepted": true
}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.