Declared read onlyLists the user's connected mailboxes with their id, address, provider (gmail, outlook, imap_smtp), connection status, Read/Write permission toggles, and per-provider capabilities.
Call this first, in any session where you do not already hold an account_id. Every other tool in this server requires an explicit account_id and none of them will infer one — including the send tools, which never guess a sending mailbox.
Read the result before acting: an account with read_enabled=false will refuse read tools, write_enabled=false will refuse writes, and the capabilities object tells you what the provider can actually do (for example can_permanently_delete is false on most IMAP servers, so email_delete_message will fail there rather than silently trashing).
Declared read onlyReturns one mailbox's address, provider, connection status, Read/Write permissions, capabilities, and last health-check result.
Use this to re-check a single account before a risky operation, or to explain a permission or capability error the user just hit — the capabilities object names exactly which operations that provider supports. To discover account ids in the first place, use email_accounts_list.
Declared read onlySearches one, several, or all Read-enabled mailboxes and returns matching messages newest-first, merged across accounts, each tagged with the account_id it came from.
This is the default way to find mail. Omit account_ids to search every connected account with Read on; pass account_ids to scope to specific mailboxes from email_accounts_list.
Results are metadata plus a snippet unless include_body is true. Page with limit and cursor; pass the same filters back alongside the cursor.
A per-account failure does not fail the call: successful accounts still return results and the failures appear in account_errors with their own code, so check that array before telling the user a search found nothing.
Declared read onlyReturns one message in full: participants, subject, timestamps, folders and labels, flags, attachment list, and optionally the body and raw headers.
Use it after email_search_messages has narrowed to the message you actually want to read, rather than searching with include_body on. The account_id must be the account that message belongs to — the one on the search result, not a different mailbox.
Attachment content is not included; the attachments array carries ids to pass to email_get_attachment.
Declared read onlyLists conversation threads matching a query across one, several, or all Read-enabled mailboxes, each with its subject, participants, message count, and latest activity.
Prefer this over email_search_messages when the user asks about a conversation rather than a specific email — 'what's happening with the Alpha contract' is a thread question, 'find the invoice PDF' is a message question.
Omit account_ids to cover every Read-enabled account. Providers without native threading are reported through their capabilities (can_thread).
Declared read onlyReturns one conversation with its messages in order, so you can read an exchange end to end instead of stitching individual messages together.
Use it after email_list_threads, or with the thread_id on any message returned by a search. The account_id must be the account that owns the thread.
Leave include_bodies false first if the thread is long; the snippets are usually enough to decide which message matters.
Declared read onlyFetches one attachment from one message. Small, safe attachments come back inline as base64 in content_base64; anything larger comes back as a short-lived signed download_url with an expires_at. Exactly one of the two is present — branch on which.
Get message_id and attachment_id from email_get_message; the ids are not guessable. An attachment over the server's size limit returns ATTACHMENT_TOO_LARGE rather than a truncated file.
Declared read onlyLists one mailbox's folders and labels, normalized to a common type (inbox, sent, drafts, trash, spam, archive, starred, important, custom) alongside the provider's own identifier.
Call this before email_move_message, email_delete_folder, or any folder-scoped search: those take folder ids from here, and the system flag tells you which folders cannot be deleted.
Declared read onlyAggregates one mailbox by sender and returns who sends the most, how much of it is unread, when they last wrote, and whether they can be unsubscribed from.
Start cleanup here rather than with email_search_messages. One call replaces paging through thousands of messages, and it hands you sender addresses, which stay valid, instead of message ids, which go stale as soon as anything moves.
The usual sequence: this tool to find the worst offenders, email_unsubscribe_sender to stop the ones that support it, then email_bulk_modify_messages with query 'from:<address>' to clear what already arrived. Show the user the counts from this tool before acting.
Reads message metadata only, never bodies, and stores per-sender totals rather than any message.
Read the result's provenance before quoting it. `source` is 'cache' or 'live'; `as_of` is when the totals were last brought current, so say 'as of an hour ago' rather than implying now; `complete` false means a scan has not yet reached the end of the mailbox and every count is a floor, not a total. `fetched` is how many messages this call actually read from the provider.
Check write requirementsAsks a sender to stop, using the List-Unsubscribe link in their own mail. Requires Write on the account because it acts outside the mailbox on the user's behalf.
Deletes nothing and moves nothing. Mail already in the mailbox stays where it is — follow this with email_bulk_modify_messages using query 'from:<address>' if the user wants it cleared too.
Only https unsubscribe links are used; a mailto-only sender returns no_unsubscribe_url rather than quietly sending mail from the account. One-click (RFC 8058) is used when the sender advertises it.
Read the result rather than assuming it worked: `success` false with a `reason` is a normal outcome, not an error. no_unsubscribe_url means the sender offers no link and the user should filter or block them instead; request_rejected means the endpoint refused. Tell the user which happened. Legitimate lists can also take a few days to take effect.
Check write requirementsCreates an unsent draft in the mailbox. Nothing is delivered — the draft appears in the user's Drafts folder where they can review or edit it.
This is the safe way to compose. Prefer it over email_send_message whenever the user has not clearly asked you to send, then hand back the draft_id so they can approve and you can call email_send_draft.
account_id chooses the mailbox and therefore the sending identity; get it from email_accounts_list and never guess. Set from only for a verified alias on that same account.
Check write requirementsReplaces the content of an existing unsent draft. Still sends nothing.
Use it to apply the user's edits to a draft you already created rather than creating a second one. Every field you supply replaces the draft's current value, so send the full recipient list and full body, not just the part that changed.
account_id must be the mailbox that owns the draft.
Check write requirementsSends a draft that already exists. This delivers mail to real people and cannot be undone — only call it when the user has approved that specific draft.
The normal flow is email_create_draft, show the user the draft, then this. account_id must be the mailbox that owns the draft.
idempotency_key is required: if the call times out, retry with the same key to learn the outcome instead of sending a second copy. The result's status is 'sent' or 'unknown' — 'unknown' means the server could not confirm delivery and did not retry, so check the mailbox before resending.
Check write requirementsComposes and immediately sends a new message. This delivers mail to real people and cannot be undone.
Only use it when the user has explicitly asked to send now. If there is any doubt about the wording, the recipients, or which mailbox to send from, use email_create_draft instead and let them approve it.
account_id selects the sending mailbox and is never inferred — take it from email_accounts_list and confirm with the user when they have more than one account. from may only be a verified alias of that account.
idempotency_key is required; retry with the same key after a timeout rather than composing a second message.
Check write requirementsSends a reply to an existing message, preserving the conversation: the server carries the provider thread id and the In-Reply-To / References headers, so the reply lands in the same thread rather than starting a new one. Quote and subject handling are automatic.
Use this instead of email_send_message any time the user is responding to something they received. reply_all defaults to false — confirm before turning it on, because it mails everyone on the original.
account_id must be the mailbox holding the message being replied to. This sends immediately; use email_create_draft with in_reply_to_message_id when the user should review first.
Check write requirementsForwards an existing message to new recipients, optionally with a note above it. Sends immediately.
Read the message first: forwarding sends its entire content, including quoted history and (unless include_attachments is false) its files, to people who have not seen any of it. Confirm the recipients with the user.
account_id must be the mailbox holding the message.
Check write requirementsChanges one message's organization state: read/unread, starred, labels added or removed, and archived or not. Returns the updated message.
Every change here is reversible — this is the tool for tidying an inbox without risking data. Omit a field to leave it alone; sending null is the same as omitting it.
Labels only work on providers whose capabilities report can_use_labels; on folder-based providers use email_move_message instead. account_id must be the mailbox holding the message.
Check write requirementsMoves one message into a different folder. The message leaves its current folder, so it will no longer be found where the user expects it.
destination_folder_id must be a folder id from email_list_folders — a folder name will be rejected. To take a message out of the inbox without filing it, use email_modify_message with archive instead.
account_id must be the mailbox holding the message; a message cannot be moved between accounts.
Check write requirementsMoves one message to the mailbox's trash. It stays recoverable for as long as the provider's retention allows, so this is the deletion to reach for by default.
Use email_delete_message only when the user has explicitly asked for permanent, unrecoverable destruction. The result's deletion field states what actually happened — 'provider_recoverable' here.
account_id must be the mailbox holding the message.
Check write requirementsPermanently destroys one message. It is not recoverable from trash and cannot be undone by anyone, including the user.
Only call this when the user has asked for permanent deletion in those terms, and confirm first. For ordinary 'delete this email' requests use email_trash_message.
confirm_permanent must be exactly true or nothing is deleted. Not every provider can do this safely — check can_permanently_delete on the account first, because an account without it returns PERMANENT_DELETE_NOT_SUPPORTED and the server will never quietly substitute a trash. idempotency_key is required.
Check write requirementsDeletes an unsent draft. Nothing was ever delivered, but the draft's content is gone and cannot be recovered — confirm before discarding work the user may still want.
account_id must be the mailbox that owns the draft. idempotency_key is required so a retry after a timeout does not report a spurious DRAFT_NOT_FOUND.
Check write requirementsTrashes or permanently deletes many messages in one mailbox. This is the most dangerous tool in the server — confirm the exact scope with the user before every call.
Select with either message_ids or query, never both and never neither. Query selection needs max_messages, and the server freezes the matching set before deleting anything. One call covers one account only; repeat per account_id from email_accounts_list.
mode 'trash' is recoverable; mode 'permanent' is not and also demands confirm_permanent: true plus the account's can_permanently_delete capability.
Large operations continue in the background: the result carries operation_id and a status of processing, which you poll with email_bulk_operation_get and can stop with email_bulk_operation_cancel. Always read deleted, failed and skipped — a partial failure is reported as partially_failed, never as success.
Check write requirementsApplies the same organization change — read, starred, labels, archive, or a move — to many messages in one mailbox.
Use it for inbox cleanup that should stay reversible, in preference to email_bulk_delete_messages. Archiving a thousand messages can be undone; deleting them cannot.
Select with either message_ids or query, never both and never neither, and set max_messages to cap a query selection. One call covers one account only.
Large operations run in the background — poll operation_id with email_bulk_operation_get and check failed and skipped before reporting success.
Declared read onlyReturns the live status and counts for a bulk delete or bulk modify — matched, processed, deleted, succeeded, failed, skipped — plus a paged list of per-message results including the error code on each failure.
Poll this after any bulk call that came back with status 'processing'. Do not tell the user an operation finished until status is 'completed'; 'partially_failed' means some messages were not changed, and the item list says which. Page through items with limit and cursor.
Check write requirementsStops a bulk operation that is still running. No further batches start; messages already processed stay changed and are not restored.
Reach for this the moment a bulk delete or modify looks wrong — it is the only way to limit the damage of an in-flight operation. The result gives the final processed, deleted, failed and remaining counts, so you can tell the user exactly how far it got.
Check write requirementsCreates a new folder or label in one mailbox and returns it with the id you will need for email_move_message and folder-scoped searches.
Check email_list_folders first — the folder the user described may already exist under a different name, and creating a near-duplicate splits their mail across two places.
account_id chooses the mailbox; folders are not shared between accounts, so organizing several mailboxes the same way means one call each.
Check write requirementsDeletes a folder from one mailbox. Confirm with the user first, and check email_list_folders for what is inside it.
With delete_contents false (the default) a folder that still holds messages returns FOLDER_NOT_EMPTY and nothing is deleted — move the messages out with email_bulk_modify_messages, then retry. With delete_contents true the messages go too.
System folders such as Inbox, Sent and Trash cannot be deleted and return SYSTEM_FOLDER_PROTECTED; the system flag on each folder tells you which those are. idempotency_key is required.
