| name | google-mail |
| description | Read, search, send, and label-manage Gmail messages for the user. |
| scope | agent |
| requires | ["google-mail"] |
Typical flows:
Find messages → google-mail_search_messages with a Gmail query. Operators: from:, to:, subject:, after:YYYY/MM/DD, before:, has:attachment, label:inbox, is:unread, newer_than:7d. Returns IDs + thread IDs only; read bodies with a separate call.
Read a message → google-mail_get_message with the id. Response is pre-flattened: headers.from/to/subject/date, textPlain, textHtml, snippet. Prefer textPlain for summarising. textHtml is mostly useful when the plaintext is empty.
Reply to a thread → read the original first so you have the right threadId → google-mail_send_message with that threadId. Subject should usually start with "Re: " (copy from the original). Gmail groups by threadId, not subject — so always pass threadId when continuing a conversation.
Send a new email → ALWAYS read back recipient, subject, and body to the user verbatim before calling google-mail_send_message. This is externally visible — no "let me send that now" without confirmation. Required: to, subject, body. Optional: cc, bcc, threadId.
Organise with labels → google-mail_list_labels to discover IDs → google-mail_modify_labels with addLabelIds / removeLabelIds. Useful ops: mark read (removeLabelIds: ['UNREAD']), archive (removeLabelIds: ['INBOX']), star (addLabelIds: ['STARRED']).
Trash a message → google-mail_trash_message. Reversible from the Gmail UI for 30 days, but still confirm with the user first.
Search returns up to maxResults messages per call — the default is 20. For broad sweeps, narrow the query (add after: or label:) rather than asking for more results.
Attachments are not handled by this skill — if the user wants an attachment, tell them you can see that it has one (has:attachment filter works) but downloading it needs a follow-up. Do not fabricate attachment contents.