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, reconnect, and delete |
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 |
DELETE /agents/{id}/email?mailboxId=... | Permanently remove a connected address |
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", "receivingMode": "forwarding" | "direct_mx" } (receivingMode defaults to forwarding). When direct_mx is chosen, mailboxSetup returns required MX and SPF records in dns and sets forwardingAddress to null. Prefer a subdomain for direct_mx: the MX record applies to the whole domain in dns[].name, so using a registrable domain redirects delivery for every mailbox on it. Entries in dns may include optional: true with a note; those are recommendations, currently a starter DMARC policy returned while domain.dmarcRecord is null, and verification does not require them. Subsequent actions include mailboxId: check, test-forwarding (or test-receiving), 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.
Delete a mailbox
DELETE /agents/{id}/email?mailboxId=... permanently removes a connected address and returns the same payload as GET /agents/{id}/email, so the response shows the remaining mailboxes and the freed allowance. This is not reversible: use the disconnect action when the address should only be paused.
Deleting applies the same revocation as disconnect first, so sending stops, queued emails are cancelled and their recipient allowance is returned, and another connected address becomes the default sender. Email history is kept and stays readable, but its messages, threads, and delivery records no longer reference a sender address; later teammate replies in those conversations fall back to the standard reply address. The address becomes available to connect again straight away. Domain verification for other addresses on the same domain is unaffected.
An address paused by an administrator returns mailbox_paused and cannot be deleted. A missing or unknown mailboxId returns a not-found or validation error.
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, delete_email_mailbox, send_email_reply, get_email_conversation, and set_email_conversation_ai with the corresponding scopes. delete_email_mailbox is irreversible and requires explicit user confirmation. Sending tools send real emails and require user authorization for the message and recipients. See the OpenAPI document for request shapes.