gws-gmail

What this skill does

# Google Gmail (gws gmail)

`gws gmail` provides CLI access to Gmail with structured JSON output.

> **Disclaimer:** `gws` is not the official Google CLI. This is an independent, open-source project not endorsed by or affiliated with Google.

## Dependency Check

**Before executing any `gws` command**, verify the CLI is installed:
```bash
gws version
```

If not found, install: `go install github.com/omriariav/workspace-cli/cmd/gws@latest`

## Authentication

Requires OAuth2 credentials. Run `gws auth status` to check.
If not authenticated: `gws auth login` (opens browser for OAuth consent).
For initial setup, see the `gws-auth` skill.

## Quick Command Reference

| Task | Command |
|------|---------|
| List recent emails | `gws gmail list` |
| List with labels | `gws gmail list --include-labels` |
| List all matches | `gws gmail list --query "label:work" --all` |
| List unread emails | `gws gmail list --query "is:unread"` |
| Search emails | `gws gmail list --query "from:[email protected]"` |
| Read a message | `gws gmail read <message-id>` |
| Read full thread | `gws gmail thread <thread-id>` |
| Send an email | `gws gmail send --to [email protected] --subject "Hi" --body "Hello"` |
| List all labels | `gws gmail labels` |
| Get label details | `gws gmail label-info --id Label_1` |
| Create a label | `gws gmail create-label --name "MyLabel"` |
| Update a label | `gws gmail update-label --id Label_1 --name "NewName"` |
| Delete a label | `gws gmail delete-label --id Label_1` |
| Add labels | `gws gmail label <message-id> --add "STARRED"` |
| Remove labels | `gws gmail label <message-id> --remove "UNREAD"` |
| Batch modify labels | `gws gmail batch-modify --ids "msg1,msg2" --add-labels "STARRED"` |
| Archive a message | `gws gmail archive <message-id>` |
| Archive a thread | `gws gmail archive-thread <thread-id>` |
| Trash a message | `gws gmail trash <message-id>` |
| Untrash a message | `gws gmail untrash <message-id>` |
| Delete a message | `gws gmail delete <message-id>` |
| Batch delete | `gws gmail batch-delete --ids "msg1,msg2"` |
| Trash a thread | `gws gmail trash-thread <thread-id>` |
| Untrash a thread | `gws gmail untrash-thread <thread-id>` |
| Delete a thread | `gws gmail delete-thread <thread-id>` |
| Reply to a message | `gws gmail reply <message-id> --body "Thanks!"` |
| Reply to all | `gws gmail reply <message-id> --body "Got it" --all` |
| Forward a message | `gws gmail forward <message-id> --to "[email protected]"` |
| Extract event ID | `gws gmail event-id <message-id>` |
| List drafts | `gws gmail drafts` |
| Get a draft | `gws gmail draft --id <draft-id>` |
| Create a draft | `gws gmail create-draft --to [email protected] --subject "Hi" --body "Hello"` |
| Update a draft | `gws gmail update-draft --id <draft-id> --body "Updated body"` |
| Send a draft | `gws gmail send-draft --id <draft-id>` |
| Delete a draft | `gws gmail delete-draft --id <draft-id>` |
| Download attachment | `gws gmail attachment --message-id <msg-id> --id <att-id> --output file.pdf` |

## Detailed Usage

### list — List recent messages/threads

```bash
gws gmail list [flags]
```

Lists recent email threads from your inbox. Each result includes:
- `thread_id` — Thread ID (use with `gws gmail thread`)
- `message_id` — Latest message ID (use with `read`, `label`, `archive`, `trash`)
- `message_count` — Number of messages in the thread

**Flags:**
- `--max int` — Maximum number of results (default 10, use `--all` for unlimited)
- `--all` — Fetch all matching results (may take time for large result sets)
- `--query string` — Gmail search query (e.g., `is:unread`, `from:[email protected]`)
- `--include-labels` — Include Gmail label IDs in the output for each thread

**Examples:**
```bash
gws gmail list --max 5
gws gmail list --query "is:unread"
gws gmail list --query "from:[email protected] subject:urgent"
gws gmail list --query "after:2024/01/01 has:attachment"
gws gmail list --include-labels
gws gmail list --query "label:work" --all
```

### thread — Read a full thread

```bash
gws gmail thread <thread-id>
```

Reads and displays all messages in a Gmail thread (conversation). Use the `thread_id` from `gws gmail list` output. Returns all messages with headers, body, labels, and `attachments` (when present) — each entry exposes `filename`, `mime_type`, `size`, `attachment_id`, and `part_id`.

### read — Read a message

```bash
gws gmail read <message-id>
```

Reads and displays the content of a specific email message. Use the `message_id` from `gws gmail list` output. When the message has attachments, the response includes an `attachments` array. Each entry has `filename`, `mime_type`, `size`, `attachment_id`, and `part_id`; pass `attachment_id` to `gws gmail attachment --id <id>` to download.

```bash
ATT_ID=$(gws gmail read <msg-id> --format json | jq -r '.attachments[0].attachment_id')
gws gmail attachment --message-id <msg-id> --id "$ATT_ID" --output file.pdf
```

### send — Send an email

```bash
gws gmail send --to <email> --subject <subject> --body <body> [flags]
```

**Flags:**
- `--to string` — Recipient email address (required)
- `--subject string` — Email subject (required)
- `--body string` — Email body (required)
- `--cc string` — CC recipients (comma-separated)
- `--bcc string` — BCC recipients (comma-separated)
- `--attachment string` — File path to attach (repeatable)

**Examples:**
```bash
gws gmail send --to [email protected] --subject "Meeting" --body "Let's meet at 3pm"
gws gmail send --to [email protected] --cc [email protected] --subject "Update" --body "Status update"
gws gmail send --to [email protected] --subject "Report" --body "See attached" --attachment /tmp/report.pdf
gws gmail send --to [email protected] --subject "Files" --body "Multiple" --attachment /tmp/a.pdf --attachment /tmp/b.png
```

### labels — List all labels

```bash
gws gmail labels
```

Lists all Gmail labels in the account, including system labels (INBOX, SENT, etc.) and user-created labels.

### label — Add or remove labels

```bash
gws gmail label <message-id> [flags]
```

**Flags:**
- `--add string` — Label names to add (comma-separated)
- `--remove string` — Label names to remove (comma-separated)

Use `gws gmail labels` to see available label names.

**Examples:**
```bash
gws gmail label 18abc123 --add "STARRED"
gws gmail label 18abc123 --add "ActionNeeded,IMPORTANT" --remove "INBOX"
gws gmail label 18abc123 --remove "UNREAD"
```

### archive — Archive a message

```bash
gws gmail archive <message-id>
```

Archives a Gmail message by removing the INBOX label. The message remains accessible via search and labels.

### archive-thread — Archive all messages in a thread

```bash
gws gmail archive-thread <thread-id>
```

Archives all messages in a Gmail thread by removing the INBOX label and marking all messages as read. Use the `thread_id` from `gws gmail list` output. More efficient than archiving individual messages for multi-message threads.

### trash — Trash a message

```bash
gws gmail trash <message-id>
```

Moves a Gmail message to the trash. Messages in trash are permanently deleted after 30 days.

### reply — Reply to a message

```bash
gws gmail reply <message-id> --body <body> [flags]
```

Replies to an existing email message within its thread. Automatically sets threading headers (In-Reply-To, References), thread ID, and Re: subject prefix.

**Flags:**
- `--body string` — Reply body (required)
- `--cc string` — CC recipients (comma-separated)
- `--bcc string` — BCC recipients (comma-separated)
- `--all` — Reply to all recipients

**Examples:**
```bash
gws gmail reply 18abc123 --body "Thanks, got it!"
gws gmail reply 18abc123 --body "Adding someone" --cc [email protected]
gws gmail reply 18abc123 --body "Sounds good" --all
```

### forward — Forward a message

```bash
gws gmail forward <message-id> --to <recipients> [flags]
```

Forwards an existing email message to new recipients. Preserves the original message content and attachments. Adds a "Fwd:" prefix to