gmail

What this skill does

# Gmail

## Available Tools

- **list_labels()**: List all Gmail labels (system: INBOX, SENT, TRASH, SPAM, DRAFT, IMPORTANT, STARRED, UNREAD; plus user-created labels).

- **list_emails(label?, max_results?, include_spam_trash?)**: List emails by label.
  - `label` (string, optional, default: "INBOX"): Label to filter by (INBOX, SENT, DRAFT, TRASH, SPAM, STARRED, IMPORTANT, or custom label ID)
  - `max_results` (integer, optional, default: 10, max: 100): Number of emails to return
  - `include_spam_trash` (boolean, optional, default: false): Include SPAM and TRASH

- **search_emails(query, max_results?)**: Search Gmail using query syntax.
  - `query` (string, required): Gmail search query (from:, to:, subject:, is:unread, has:attachment, after:, before:, older_than:, newer_than:)
  - `max_results` (integer, optional, default: 10, max: 50): Number of results

- **read_email(message_id)**: Read a full email including body and attachments.
  - `message_id` (string, required): Gmail message ID (from list_emails or search_emails)

- **send_email(to, subject, body, cc?, bcc?, reply_to?, in_reply_to?, html_body?)**: Send an email.
  - `to` (string, required): Recipient(s), comma-separated
  - `subject` (string, required): Email subject
  - `body` (string, required): Plain text email body
  - `cc` (string, optional): CC recipient(s)
  - `bcc` (string, optional): BCC recipient(s)
  - `reply_to` (string, optional): Reply-To address
  - `in_reply_to` (string, optional): Message-ID to reply to (for threading)
  - `html_body` (string, optional): HTML version of email body

- **draft_email(to, subject, body, cc?, bcc?, reply_to?, in_reply_to?, html_body?)**: Create a draft for later editing/sending. Same parameters as `send_email`.

- **delete_email(message_id, permanent?)**: Delete an email.
  - `message_id` (string, required): Gmail message ID
  - `permanent` (boolean, optional, default: false): If true, permanently delete; if false, move to Trash

- **bulk_delete_emails(query, reason, max_delete?)**: Permanently delete multiple emails by query. **Cannot be undone.**
  - `query` (string, required): Gmail search query to find emails
  - `reason` (string, required): Human-readable explanation (shown to user for approval)
  - `max_delete` (integer, optional, default: 50, max: 100): Maximum emails to delete

- **modify_email(message_id, add_labels?, remove_labels?)**: Add/remove labels on an email.
  - `message_id` (string, required): Gmail message ID
  - `add_labels` (string, optional): Comma-separated label IDs to add (e.g., "STARRED,IMPORTANT")
  - `remove_labels` (string, optional): Comma-separated label IDs to remove (e.g., "UNREAD,INBOX")

- **get_email_thread(thread_id)**: Get all messages in an email thread/conversation.
  - `thread_id` (string, required): Gmail thread ID (from read_email or search_emails)

## Usage Guidelines

- Use `list_labels` first to discover available labels before filtering.
- Gmail search query syntax: `from:sender`, `to:recipient`, `subject:text`, `is:unread`, `has:attachment`, `after:2024/01/01`, `before:2024/12/31`.
- Use `get_email_thread` to view entire conversation context before replying.

## Common Operations

Label operations via `modify_email`:

| Operation | Parameters |
|-----------|-----------|
| Mark as read | `remove_labels="UNREAD"` |
| Mark as unread | `add_labels="UNREAD"` |
| Archive | `remove_labels="INBOX"` |
| Star | `add_labels="STARRED"` |
| Unstar | `remove_labels="STARRED"` |
| Mark important | `add_labels="IMPORTANT"` |

## Bulk Deletion

`bulk_delete_emails(query, reason)` **permanently** deletes all emails matching a Gmail query. This cannot be undone.

- Always provide a `reason` parameter explaining the intent.
- Always explain what will be deleted and get user confirmation before calling.

Common queries:
- Spam cleanup: `"is:spam older_than:7d"`
- Old unread: `"in:inbox is:unread older_than:14d"`
- Promotions purge: `"category:promotions older_than:30d"`
- From specific sender: `"from:[email protected] older_than:30d"`

## UI Guidance (from tools-config)

**Gmail Tool Usage:**
- list_labels: Get all available labels before filtering emails
- list_emails: Browse emails by label (INBOX, SENT, DRAFT, TRASH, etc.)
- search_emails: Use Gmail query syntax (from:, to:, subject:, is:unread, has:attachment, after:, before:)
- read_email: Get full email content with attachments
- send_email: Send emails with optional CC, BCC, and HTML body
- draft_email: Create drafts for later editing/sending
- delete_email: Move to trash (permanent=True for permanent deletion)
- bulk_delete_emails: Permanently delete multiple emails by query (requires user approval)
- modify_email: Add/remove labels (mark read: remove UNREAD, archive: remove INBOX, star: add STARRED)
- get_email_thread: View entire conversation thread

**Bulk Deletion (bulk_delete_emails):**
- Use for spam cleanup, old email purge, etc.
- Always provide 'reason' parameter explaining the intent
- Common queries: "is:spam older_than:7d", "in:inbox is:unread older_than:14d", "category:promotions older_than:30d"
- WARNING: Permanently deletes emails - cannot be recovered

**Common Operations:**
- Mark as read: modify_email(id, remove_labels="UNREAD")
- Archive: modify_email(id, remove_labels="INBOX")
- Star: modify_email(id, add_labels="STARRED")
- Mark important: modify_email(id, add_labels="IMPORTANT")