gmail

This skill provides Gmail-specific operations beyond the shared **messaging** skill. For cross-platform messaging (send, read, search, reply), use the messaging skill. Gmail operations depend on the messaging skill's provider infrastructure - load messaging first if Gmail is not yet connected.

## Script Reference

All operations use CLI scripts that return JSON:

- **Success**: `{ "ok": true, "data": ... }`
- **Failure**: `{ "ok": false, "error": "..." }`

| Script             | Operation               | Description                                                                  |
| ------------------ | ----------------------- | ---------------------------------------------------------------------------- |
| `gmail-email.ts`   | `draft`                 | Create email drafts in the Drafts folder (including reply drafts)            |
| `gmail-email.ts`   | `send-draft`            | Send an existing draft (**requires explicit user confirmation**)             |
| `gmail-email.ts`   | `forward`               | Create forward drafts, preserving attachments                                |
| `gmail-email.ts`   | `trash`                 | Move messages to Trash                                                       |
| `gmail-manage.ts`  | `label`                 | Add or remove labels on messages                                             |
| `gmail-manage.ts`  | `follow-up`             | Track/untrack messages for follow-up using a dedicated "Follow-up" label     |
| `gmail-manage.ts`  | `attachments`           | List and download email attachments                                          |
| `gmail-manage.ts`  | `filters`               | Create, list, and delete Gmail filters                                       |
| `gmail-manage.ts`  | `vacation`              | Get, enable, or disable the vacation auto-responder                          |
| `gmail-manage.ts`  | `unsubscribe`           | Unsubscribe from mailing lists (**requires explicit user confirmation**)     |
| `gmail-scan.ts`    | `sender-digest`         | Scan inbox and group messages by sender for declutter workflows              |
| `gmail-scan.ts`    | `outreach-scan`         | Identify cold outreach senders (no List-Unsubscribe header)                  |
| `gmail-archive.ts` | `archive`               | Archive messages (single, batch message_ids, cache_key+sender-emails, query) |
| `gmail-archive.ts` | `archive --dry-run`     | Preview what would be archived without executing (writes staged ops to log)  |
| `gmail-archive.ts` | `archive --resume`      | Resume an interrupted archive run from its last checkpoint                   |
| `gmail-commit.ts`  | `commit`                | Execute all staged ops from a dry-run                                        |
| `gmail-commit.ts`  | `cancel`                | Delete a run log without executing anything                                  |
| `gmail-runs.ts`    | `list`                  | List recent operation runs with status summaries                             |
| `gmail-runs.ts`    | `inspect`               | Show detailed log entries for a specific run                                 |
| `gmail-runs.ts`    | `prune`                 | Delete operation logs older than 30 days                                     |
| `gmail-reverse.ts` | `--run-id`              | Reverse all committed ops in a run (un-archive, un-label, un-trash)          |
| `gmail-reverse.ts` | `--run-id --thread`     | Reverse a specific message within a committed run                            |
| `gmail-prefs.ts`   | `list`                  | List blocklist and safelist preferences                                      |
| `gmail-prefs.ts`   | `add-blocklist`         | Add sender emails to the blocklist                                           |
| `gmail-prefs.ts`   | `add-safelist`          | Add sender emails to the safelist                                            |
| `gmail-prefs.ts`   | `remove-blocklist`      | Remove sender emails from the blocklist                                      |
| `gmail-prefs.ts`   | `remove-safelist`       | Remove sender emails from the safelist                                       |
| `gmail-prefs.ts`   | `get-management-config` | Get inbox management config (stage, interrupt threshold, last run)           |
| `gmail-prefs.ts`   | `set-management-config` | Update inbox management config (--stage, --interrupt-threshold, --last-run)  |

### Email Operations

```bash
# Draft an email
bun run scripts/gmail-email.ts draft --to "user@example.com" --subject "Hello" --body "Message body"

# Draft a reply in a thread
bun run scripts/gmail-email.ts draft --to "user@example.com" --subject "Re: Hello" --body "Reply body" --thread-id "18f..." --in-reply-to "18f..."

# Send an existing draft (REQUIRES user confirmation before execution)
bun run scripts/gmail-email.ts send-draft --draft-id "r123..."

# Forward a message
bun run scripts/gmail-email.ts forward --message-id "18f..." --to "recipient@example.com" --text "FYI"

# Trash a message
bun run scripts/gmail-email.ts trash --message-id "18f..."
```

### Management Operations

```bash
# Label - add a label to a message
bun run scripts/gmail-manage.ts label --message-id "18f..." --add-labels "Work,Important"

# Follow-up - track a message for follow-up
bun run scripts/gmail-manage.ts follow-up --action track --message-id "18f..."

# Attachments - list attachments on a message
bun run scripts/gmail-manage.ts attachments --action list --message-id "18f..."

# Attachments - download a specific attachment
bun run scripts/gmail-manage.ts attachments --action download --message-id "18f..." --attachment-id "ANGj..." --filename "report.pdf"

# Filters - create a Gmail filter
bun run scripts/gmail-manage.ts filters --action create --from "newsletter@example.com" --remove-labels "INBOX"

# Vacation - enable auto-responder
bun run scripts/gmail-manage.ts vacation --action enable --message "I'm out of office until Monday"

# Unsubscribe from a mail