manage_email
Search, read, send, forward, and manage Gmail emails using Gmail search syntax. Organize messages with labels, filters, and bulk actions.
Instructions
Search, read, send, forward, or manage emails in a Google Workspace account. Supports Gmail search syntax.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | CC email(s), comma-separated. On `replyAll` these are ADDITIONAL — they do not replace the recipients already on the thread. | |
| to | No | Recipient email(s), comma-separated | |
| bcc | No | BCC email(s), comma-separated | |
| body | No | Email body text. On `forward`, an optional note prepended ABOVE the forwarded message. | |
| 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. | |
| draft | No | Save as draft instead of sending (default: false, forced true when attachments present) | |
| Yes | Account email address | ||
| query | No | Gmail search query (e.g. "from:alice subject:meeting has:attachment") | |
| 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). | |
| 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. | |
| threadId | No | Thread ID to retrieve | |
| forwardTo | No | Filter action: forward each match to this address. It must already be a verified forwarding address in Gmail settings. | |
| 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: save an email's headers and body to a markdown file in the workspace — a LOCAL archive, not Gmail's 'remove from inbox' (attachments are listed, not downloaded) | send: compose and send a new email (creates draft when attachments present, 35MB attachment limit via upload endpoint) | reply: reply to a message (thread-aware, creates draft when attachments present) | replyAll: reply-all to a message (thread-aware, includes all recipients, creates draft when attachments present) | forward: forward a message to new recipients (includes original attachments by default) | triage: unread inbox summary (sender, subject, date) | trash: move a message to 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. | 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`. | 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, removeLabelIds and forwardTo. 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: get all messages in a 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. | |
| outputPath | No | Local path to save the markdown file (workspace-relative; defaults to a slug from the message date and subject) | |
| 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). Creates draft when present. | |
| 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. | |
| 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 |