Email channel
Manage business email connections and queue teammate replies through the public API or MCP.
The API follows the dashboard’s email setup, recipient allowances, and delivery rules. Existing keys need the new scopes before using these operations. Key restrictions on agents apply throughout.
| Scope | Access |
|---|---|
read:email | List mailboxes and read setup |
write:email | Connect, check, test, activate, customize, disconnect, and reconnect |
read:conversations | Read email recipients, delivery outcomes, and review state |
write:conversations | Queue teammate email replies and control future automatic replies |
write:chat continues to request an AI answer; it does not authorize teammate email delivery.
Endpoints
Paths start with /api/v1. Authenticate with Authorization: Bearer YOUR_API_KEY.
| Method and path | Purpose |
|---|---|
GET /agents/{id}/email | Mailboxes, available Functions, allowances |
GET /agents/{id}/email?mailboxId=... | One mailbox’s setup |
POST /agents/{id}/email | Mailbox action |
POST /agents/{id}/email/conversations | Create an empty conversation using email, subject, optional name/mailboxId, and idempotencyKey |
POST /agents/{id}/email/replies | Queue a reply in an existing conversation |
GET /agents/{id}/email/conversations/{sessionId} | Recipients, outcomes, review reasons |
POST /agents/{id}/email/conversations/{sessionId} | { "resume": true } or { "resume": false } |
Forwarding confirmation messages from your email provider are visible only in the dashboard.
Connect with { "action": "create", "address": "[email protected]", "name": "Support" }. Subsequent actions include mailboxId: check, test-forwarding, test-sending, activate, disconnect, or reconnect. Test actions send real emails. update accepts a settings object containing name, signature, instructions, aiEnabled, isDefault, and toolAllowlist. Use tool names returned in tools. The optional mail-from action accepts enabled.
Queue a reply
{
"sessionId": "email:YOUR_CONVERSATION_ID",
"content": "Thank you. We have received your request.",
"idempotencyKey": "support-reply-2026-000123",
"to": ["[email protected]"],
"cc": []
}HTTP 202 returns deliveryId, messageId, and status. Queued is saved, not delivered. Poll the conversation endpoint for outcomes. Reuse the same idempotency key with identical input on request retries. Different input with the same key returns a conflict. Do not create a new key automatically after a timeout; uncertain delivery requires review.
Optional subject and mailboxId are supported. A conversation already bound to a mailbox must retain it. Omitting To/CC uses approved participants. Approve recipient changes before sending; ten recipients maximum, no BCC. Public replies currently send text; use the dashboard for attachments.
Setup conflicts, exhausted allowances, disconnected mailboxes and unavailable AI states return actionable errors. Temporary service failures may require retrying. Incoming messages continue when sending allowance runs out.
MCP
Use create_email_conversation, list_email_mailboxes, manage_email_mailbox, send_email_reply, get_email_conversation, and set_email_conversation_ai with the corresponding scopes. Sending tools send real emails and require user authorization for the message and recipients. See the OpenAPI document for request shapes.