Email tools

A connected mailbox is also an agent tool family: read, search, open, send, reply, mark, and move mail. All owner-only, and distinct from Email-as-a-channel.

The mailbox you connect as the Email channel is dual-surface: besides replying to inbound mail, it hands your agent a tool family: read the inbox, search, open a message, send, reply in-thread, mark read/unread, and move messages. Every one of these tools is owner-only. Here's what an internal agent can do with a mailbox as tools.

Connect

There is no separate connect step for the email tools. Connecting the Email channel is what turns them on. The same mailbox row powers both surfaces.

Connect a mailbox under Channels → Add channel → Email: Gmail sign-in, or IMAP/SMTP for any other provider. Full steps live on the Email channel page.
Attach that connection to an internal agent (the dashboard or BotFather). The email tools only appear for internal callers.
Talk to the agent. Ask it to check the inbox, search a sender, or draft a reply.

The enabling gotcha: these tools are owner-only. They run only on internal surfaces and never for a website visitor, because a mailbox holds private mail. A public web-chat agent will not see them even after you connect. And the channel's Read-only setting is the on/off switch for the write half: flip it on and send, reply, mark, and move disappear, leaving only the read tools.

What the agent can do

Tool	Access	Type	What it does
`email_list_accounts`	Owner-only	Read	Lists the mailboxes connected to this agent with their address, provider, and status. Call it first when more than one is connected to get the account uid.
`email_read_inbox`	Owner-only	Read	Lists recent messages from a folder (default INBOX) with subject, sender, date, and read status.
`email_search`	Owner-only	Read	Searches a folder by keyword across subject, sender, and body; returns matching messages.
`email_get_message`	Owner-only	Read	Opens one message by its id: full subject, from/to/cc, date, and body text.
`email_send`	Owner-only	Write	Sends a new email (plain text or HTML) with optional CC and BCC, from the connected address.
`email_reply`	Owner-only	Write	Replies to a message in-thread. Sets the threading headers and prepends 'Re:' to the subject.
`email_mark_read`	Owner-only	Write	Marks a message read or unread.
`email_move`	Owner-only	Write	Moves a message to another folder or label: Trash, Archive, and the like.

Owner-only, and the read/write split

None of these are public-safe. All eight are gated on an internal caller plus the email add-on being present, and every call is marked sensitive so it stays hidden from the chat stream. Within that, there are two tiers: the four read tools (list accounts, read inbox, search, get message) and the four write tools (send, reply, mark read, move). The channel's Read-only toggle removes the write four. A read-only mailbox lets the agent triage and quote mail but never act on it.

Worked example

You tell your internal support agent: "Check my inbox for anything from Acme this week, and if they asked about the invoice, reply that it's on the way." The agent runs email_search for Acme, email_get_message to read the thread, then email_reply to answer in-thread under your from-name and signature, one round-trip, no context-switching to your mail client.

Limits & honesty

Writes are real sends. email_send and email_reply deliver to real recipients from your real address. Test on an internal agent first.
Read-only is the guard. With the channel's Read-only setting on, the write tools are hidden entirely. The agent can read but never send, mark, or move.
Ids are opaque, and provider-shaped. A message id is a number for IMAP mailboxes and a string for Gmail. Always pass back exactly what email_read_inbox or email_search returned; don't guess.
Pick the mailbox when there's more than one. With multiple mailboxes connected, call email_list_accounts first and pass the account_uid; with a single mailbox it's chosen for you.

Troubleshooting

Agent can't see the email tools. You're likely on a public/web-chat agent. The family is owner-only; attach the mailbox to an internal agent.
Reads work, sending is refused: the mailbox is in Read-only mode, or (for IMAP) the SMTP half failed to authenticate. Check both.
"No email accounts connected": the mailbox isn't attached to this agent, or the connection errored. Reconnect from Channels.

FAQ

Is this different from the Email channel? Same connection, second surface. The channel replies to inbound mail; the tools let an internal agent read and act on the whole mailbox.

Can a website visitor read my inbox? Never, all eight tools are owner-only and stay off customer-facing agents.

Can I connect more than one mailbox? Yes, each has its own account_uid; list accounts first, then target one.

Email channel, the other half: inbound mail as conversations
Google Workspace, Drive, Docs, Calendar, and Gmail
Agent abilities, how tools attach to an agent
Integrations overview