E-mails

The messages that arrived on your inboxes, their parsed content and their processing state. Five tools.

See the Email model for the shape of the returned object and the received → approved | rejected → processing → processed | failed state machine.

---

emails_list

Read · scope inbox/emails · permission emails.list · GET /emails

List received e-mails in the selected workspace. Cursor-paginated. Bodies are not included — use emails_get for those.

Parameter	Type	Description
cursor	string	Opaque cursor from a previous page.
limit	integer	Page size, default 25, max 100.
sort	string	Sort keys, - prefix for descending.
status	received | approved | rejected | processing | processed | failed	Filter by processing status.
inbox_id	string (uuid)	Only mail received on this inbox.
agent_id	string (uuid)	Only mail processed by this agent.
message_id	string	Filter by RFC 5322 Message-ID.
from	string	Exact match on the sender.
to	string	Matches when the address appears in the recipient array.
created_at_gte / created_at_lte	string	ISO 8601 range on created_at.
received_at_gte / received_at_lte	string	ISO 8601 range on received_at.
processed_at_gte / processed_at_lte	string	ISO 8601 range on processed_at.

emails_get

Read · scope inbox/emails · permission emails.show · GET /emails/{id}

Fetch one e-mail, including the parsed text and HTML bodies.

Parameter	Type	Description
id required	string (uuid)	E-mail id.

emails_download_eml

Read · scope inbox/emails · permission emails.download · GET /emails/{id}/eml

Return a short-lived presigned URL for the original .eml, with full headers, MIME parts and attachments. The URL expires in 60 seconds and is not re-fetchable — download it before it lapses.

The raw message is deliberately not returned inline: a tool result enters the model's context and may be persisted by the client.

Parameter	Type	Description
id required	string (uuid)	E-mail id.

emails_reprocess

Destructive · scope inbox/emails + write · permission emails.reprocess · POST /emails/{id}/reprocess

Re-enqueue an e-mail for its agent. Accepts only approved, processed or failed; anything else is 422. Answers 202 — the run happens in the worker, not in this call.

Parameter	Type	Description
id required	string (uuid)	E-mail id.
agent_id	string (uuid)	Override the agent for this run; defaults to the inbox's current agent.
idempotency_key	string	Replay guard, 8–255 chars.

emails_delete

Destructive · scope inbox/emails + write · permission emails.delete · DELETE /emails/{id}

Soft-delete an e-mail. The record stops appearing in every read path.

Parameter	Type	Description
id required	string (uuid)	E-mail id.