| 1 | --- |
| 2 | name: gmail |
| 3 | description: Search, read, draft, and send Gmail via the Gmail API. Use when: email, inbox, unread mail, sending mail, newsletters, or anything gmail. |
| 4 | invocation: model+user |
| 5 | --- |
| 6 | |
| 7 | # Gmail |
| 8 | |
| 9 | ## When to use |
| 10 | Reading, searching, drafting, or sending email in the user's Gmail account. |
| 11 | |
| 12 | ## Setup |
| 13 | Requires Google auth with a Gmail scope. Fail loud when it is missing: |
| 14 | |
| 15 | ``` |
| 16 | gcloud auth application-default login --scopes=openid,https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/calendar |
| 17 | TOKEN=$(gcloud auth application-default print-access-token) |
| 18 | ``` |
| 19 | |
| 20 | The Gmail API must be enabled on the user's Google Cloud project. Never ask |
| 21 | for or store the user's Google password — OAuth tokens only. |
| 22 | |
| 23 | ## Workflow |
| 24 | 1. Search first, read second: `GET gmail/v1/users/me/messages?q=...`, then |
| 25 | `GET gmail/v1/users/me/messages/{id}?format=full`. |
| 26 | 2. Summarize threads; quote sender, date, and subject for anything actionable. |
| 27 | 3. Drafts are safe to create; **sending needs explicit user approval every |
| 28 | time**, showing recipient, subject, and full body first. |
| 29 | 4. Attachments: download via `messages.attachments.get`, never execute them. |
| 30 | |
| 31 | ## Non-goals |
| 32 | - Do not send, delete, or archive mail on your own initiative. |
| 33 | - Do not subscribe, unsubscribe, or change filters/labels unless asked. |
| 34 | - Do not paste credentials or tokens into chat or files outside the auth flow. |
| 35 |