manage_email
Manage Gmail messages and threads: search, read, triage, label, archive, trash, report spam, and handle drafts, labels, and filters. Does not send mail.
Instructions
Search, read, triage, label, archive, trash, report spam, and manage drafts, labels and filters in a Google Workspace account. Supports Gmail search syntax. This tool sends nothing: sending, replying and forwarding are send_email.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | CC email(s), comma-separated | |
| to | No | Recipient email(s), comma-separated | |
| bcc | No | BCC email(s), comma-separated | |
| body | No | Email body text | |
| from | No | Sender email or RFC 2822 mailbox for a verified Gmail Send As alias | |
| html | No | Treat body as HTML content (default: plain text) | |
| name | No | Label name, e.g. 'REC/Receipt'. Nested labels use a slash; create the parent first if Gmail shows nesting. | |
| Yes | Account email address. On list operations, "all" runs it once for every configured account. | ||
| query | No | Gmail search query (e.g. "from:alice subject:meeting has:attachment") | |
| format | No | For getThread: full (default) includes each message's body; metadata is From, To, Subject and Date only | |
| draftId | No | Draft id as returned by listDrafts (an r… id, not the message id) | |
| idsOnly | No | On `search`: return only message ids, up to 500 per page, without fetching each message's headers. For counting a large result or collecting ids to pass to bulk_operations batch mode (e.g. modify). | |
| labelId | No | Label ID (from `labels`), e.g. Label_123 — not the label name | |
| matchTo | No | Filter criterion: recipient, e.g. a list or alias address | |
| subject | No | Email subject line | |
| filename | No | Attachment filename, exactly as it appears in the `read` response (e.g. 'invoice_template.md') | |
| filterId | No | Filter id, as listed by `filters`. On previewFilter, the filter a change would replace; leave it out to preview a new filter. | |
| replyAll | No | For a reply draft: include everyone on the thread, as reply-all does (default: reply to the sender) | |
| threadId | No | Thread ID to retrieve | |
| matchFrom | No | Filter criterion: sender, e.g. billing@vendor.com or @vendor.com | |
| matchSize | No | Filter criterion: size in bytes; requires matchSizeComparison | |
| messageId | No | Email message ID | |
| operation | Yes | search: find emails by query. Says when more results exist than the page shows; continue with pageToken, or pass idsOnly to collect up to 500 ids per page for bulk_operations. | read: get full email by ID. Pass bodyFormat: 'html' when the plain-text part is a stub (marketing email, invitations, booking confirmations) and the dates/codes you need only exist in the HTML — returned HTML is sanitized and wrapped in a Spotlighting block (ADR-305). | archive: archive a message, as Gmail's Archive button does: it leaves the inbox but stays in All Mail with its other labels. `unarchive` puts it back. | unarchive: move an archived message back to the inbox | markRead: mark a message as read | markUnread: mark a message as unread | triage: unread inbox summary (sender, subject, date) | trash: move a message to trash | markSpam: report a message as spam: moves it out of the inbox into Spam | unmarkSpam: not spam: moves a message from Spam back to the inbox | modifyThread: add or remove labels on every message in a thread at once (e.g. a label on the whole conversation; removeLabelIds UNREAD marks it all read) | archiveThread: archive a whole conversation: every message in the thread leaves the inbox | unarchiveThread: move a whole conversation back to the inbox | markThreadSpam: report a whole conversation as spam: every message moves out of the inbox into Spam | unmarkThreadSpam: not spam: moves a whole conversation from Spam back to the inbox | trashThread: move a whole conversation (every message in the thread) to trash | untrashThread: restore a whole conversation from trash | untrash: restore a message from trash | listDrafts: list saved drafts (unsent messages) with each draft's DRAFT id (the r… id), recipient, subject and date. Use that draft id with deleteDraft — a message id from search in:drafts will not work for deletion. | createDraft: save a new draft without sending it. Give to, subject and body for a new message; give replyToMessageId instead for a reply draft in that message's thread (recipients, subject and quoting are filled in, as for a reply). Returns the draft id (r…). | getDraft: read a draft by its draft id (the r… id from listDrafts or createDraft): recipients, subject, body and attachments | updateDraft: change a draft without sending it. Only the fields you give change; recipients, subject, body and attachments you leave out are kept, and a reply draft stays in its thread. `body` replaces the whole text; `attachments` replaces all attachments. | deleteDraft: permanently delete a draft (unsent message) by its draft id (the r… id returned by listDrafts). Irreversible — the draft is discarded, not moved to trash. | getAttachment: download an email attachment to workspace directory (use read first to see attachment list) | viewAttachment: view an image attachment inline without saving to workspace (png, jpg, gif, webp). Use for quick preview — use getAttachment to save. | modify: add or remove labels on a message (e.g. archive, mark read/unread) | previewModifyMatching: evaluate a label change over everything a query matches, without making it: the exact count (up to 10,000), a sample, and what the change does to each message. Holds the matched set and returns the previewToken modifyMatching needs. No ids are returned beyond the sample. | modifyMatching: apply a previewed label change (archive, mark read, label, trash) to exactly the messages previewModifyMatching counted, and report how many changed. Requires its previewToken from an earlier call, within 30 minutes; each preview applies once. | labels: list all labels in the mailbox | createLabel: create a label. A slash in the name makes it nested (e.g. 'REC/Receipt' under 'REC'). Fails if the name already exists. Use `labels` first to check, then pass the returned label ID to `modify`. | updateLabel: rename a label or change where it shows. Only the fields you give change. Renaming 'REC' does not rename nested 'REC/…' labels. | deleteLabel: delete a label. The messages themselves stay where they are; they just lose this label. Irreversible. | filters: list the account's filters: id, criteria and what each does. Gmail allows 1,000. | getFilter: one filter's criteria and actions in words, plus the parameters that recreate or edit it | previewFilter: evaluate a filter without creating it: how many messages it matches today and a sample, what each action does, and any duplicate or overlapping filter. Returns the previewToken createFilter needs; with filterId, previews replacing that filter and returns the token updateFilter needs. Criteria are the match* params; actions are addLabelIds and removeLabelIds (filters cannot forward mail in this build). A good criterion is the query of a search that already found the mail. | createFilter: create a filter. Requires the previewToken from previewFilter called with the same parameters, in an earlier call, within 30 minutes. Acts on mail arriving from then on. | updateFilter: change a filter's criteria or actions. Gmail has no in-place update, so this creates the replacement and then deletes the original; the filter gets a new id. Requires the previewToken from previewFilter called with filterId and the same parameters. | deleteFilter: delete a filter. Returns what it was and the parameters to recreate it. | threads: list email threads by query | getThread: read a whole conversation: every message in the thread with its sender, date and body. Pass format metadata for headers only, to skim a long thread. | |
| pageToken | No | Continue a list from where the previous page stopped: pass the pageToken its response gave. Absent from a response means that response was the last page. | |
| bodyFormat | No | How to render the message body. 'plain' (default) returns text/plain or a crude HTML-strip fallback. 'html' returns the text/html part sanitized — useful when the plain-text part is empty/stub. | |
| matchQuery | No | Filter criterion: any Gmail search query the message must match, same syntax as search | |
| maxResults | No | Max results per page (default 10, max 50). On `search` with idsOnly, default and max 500. | |
| addLabelIds | No | Comma-separated label IDs to add (e.g. STARRED, IMPORTANT, Label_123). On modify, to this message; on the filter operations, to each matching message as it arrives; on the *ModifyMatching operations, to every message the preview counted. | |
| attachments | No | Workspace filenames to attach, comma-separated (files must exist in workspace via manage_workspace) | |
| matchSubject | No | Filter criterion: words in the subject | |
| previewToken | No | The token the preview returned for this exact change: previewFilter for createFilter and updateFilter, previewModifyMatching for modifyMatching. Required: the write runs only after its preview has been seen. | |
| removeLabelIds | No | Comma-separated label IDs to remove (e.g. UNREAD to mark read, INBOX to archive). On modify, from this message; on the filter operations, from each matching message as it arrives; on the *ModifyMatching operations, from every message the preview counted. | |
| replyToMessageId | No | For createDraft: make it a reply draft to this message id, in its thread | |
| matchExcludeChats | No | Filter criterion: leave chat messages out | |
| matchNegatedQuery | No | Filter criterion: a Gmail search query the message must NOT match | |
| matchHasAttachment | No | Filter criterion: only messages with an attachment | |
| labelListVisibility | No | Whether the label appears in the label list: labelShow (default), labelShowIfUnread, or labelHide | |
| matchSizeComparison | No | Filter criterion: whether matches are larger or smaller than matchSize | |
| messageListVisibility | No | Whether the label appears on messages in the message list: show (default) or hide |