gw-gmail

Files (1)

• SKILL.md

SKILL.md (first lines)

# Gmail

## Invocation

```bash
CLI="python3 ${CLAUDE_PLUGIN_ROOT}/cli/gw.py"
```

## Account Routing

Accounts are user-defined in `accounts.json` (see `gw auth list` / `gw auth login --account <name>`); the names and emails below are only examples.

| Account | Example email | Typical use |
|---|---|---|
| `--account main` | `you@example.com` | Primary (default) |
| `--account work` | `work@example.com` | Work / outreach |
| `--account personal` | `personal@example.com` | Personal |

## Commands

### Send & Draft

Always use `--body-file -` with heredoc. Never `--body "..."` — special characters break shell quoting.

```bash
$CLI gmail send --to EMAIL --subject "..." --body-file - [--cc "a@x.com,b@y.com"] [--thread-id TID] [--attach FILE] [--no-signature] [--plain | --html-body HTML] [--account work] <<'BODY'
Email body here.
BODY

$CLI gmail draft --to EMAIL --subject "..." --body-file - [--cc "a@x.com,b@y.com"] [--thread-id TID] [--attach FILE] [--no-signature] [--plain | --html-body HTML] [--account work] <<'BODY'
Draft body here.
BODY
```

Multiple recipients: `--to` and `--cc` accept comma-separated addresses or repeated flags. Always comma-separate in one string for clarity: `--cc "a@x.com,b@y.com,c@z.com"`.

Signature: the account's Gmail send-as signature is appended to the HTML part by default. `--no-signature` omits it (for a body that carries its own sign-off block). The flag works on every verb that builds a message: `send`, `draft`, the four reply verbs, `update-draft` and `attach-to-draft`.

Plain text: `--plain` sends the body as a single `text/plain` part with no HTML alternative, so there is no signature and no styling, and the recipient's mail client shows it in its own default font, like a hand-typed email. Threading, To/Cc, the From display name and attachments are unchanged. Works on `send`, `draft` and the four reply verbs. Default (without the flag) is plain + HTML with the signature.

Your own HTML: `--html-body HTML` sends `HTML` verbatim as the `text/html` alternative, with the `--body` text as the `text/plain` part. It implies no signature: the send-as signature is not appended, the HTML is not wrapped or styled, and nothing in it is converted. Pass it from a file with `--html-body "$(cat /path/to/body.html)"`. Threading, To/Cc, the From display name and attachments are unchanged. Works on `send`, `draft` and the four reply verbs. `--html-body` with `--plain` is a usage error.

Response: `{"sent":true,"id":"MSG_ID","threadId":"TID"}` or `{"drafted":true,"id":"DRAFT_ID","messageId":"MSG_ID"}`

### Attachments

**The CLI fully supports file attachments.** Use `--attach` with an absolute file path. Repeat for multiple files.

```bash
# Single attachment
$CLI gmail send --to EMAIL --subject "..." --attach /path/to/file.pdf --body-file - <<'BODY'
See attached.
BODY

# Multiple attachments
$CLI gmail draft --to EMAIL --subject "..." --attach /path/to/report.pdf --attach /path/to/data.csv --body-file - <<'BODY'
Two files attached.
BODY

# Attachment on a draft reply
$CLI gmail draft-reply MESSAGE_ID --attach /path/to/file.pdf --body-file - <<'BODY'
Attaching the document you requested.
BODY
```

Works on: `send`, `draft`, `draft-reply`. Any file type. Uses MIME multipart/mixed encoding. Supports `~/` paths.

**Quote paths with spaces** (e.g. Google Drive): `--attach "/path/with spaces/file.pdf"`

### Reply

All four reply commands preserve the thread, add a `Re:` subject prefix if missing, and include your display name + signature from `sendAs` (`--no-signature` omits the signature; `--plain` sends plain text only, with no HTML and so no signature; `--html-body` sends your own HTML with no signature). **Original Cc is auto-preserved** on plain reply/draft-reply (minus your own address). Override with `--cc "a@x,b@y"` or clear with `--no-cc`.

```bash
# Plain reply (To = original sender, Cc preserved from original)
$CLI gmail reply MESSAGE_ID --body-file - [--cc "a@x,b@y"] [--no-cc] [--to EMAIL] [--attach FILE] [--no-signature] [--plain | --html-body HTML] [--account work] <<'BODY'
Reply text.
BODY

# Plain draft reply — does NOT send
$CLI gmail draft-reply MESSAGE_ID --body-file - [--cc "a@x,b@y"] [--no-cc] [--to EMAIL] [--attach FILE] [--no-signature] [--plain | --html-body HTML] [--account work] <<'BODY'
Draft reply text.
BODY

# Reply-all: To = original sender, Cc = original To + Cc, deduped, minus self
$CLI gmail reply-all MESSAGE_ID --body-file - [--cc "..."] [--no-cc] [--to EMAIL] [--attach FILE] [--no-signature] [--plain | --html-body HTML] <<'BODY'
Reply to everyone on the thread.
BODY

# Draft reply-all — does NOT send
$CLI gmail draft-reply-all MESSAGE_ID --body-file - [--cc "..."] [--no-cc] [--to EMAIL] [--attach FILE] [--no-signature] [--plain | --html-body HTML] <<'BODY'
Draft reply to everyone.
BODY
```

**Cc behavior:**
- Default (no flag): plain `reply`/`draft-reply` preserves the original Cc list. `reply-all`/`draft-reply-all` expands Cc to include original To recipients too (minus you, minus whoever's in your new To).
- `--cc "frank@w.com,gina@x.com"`: explicit override, discards original Cc.
- `--no-cc`: force Cc empty. Conflicts with `--cc`.
- `--to "dave@z.com"`: override the primary recipient. In reply-all, the original sender moves to Cc instead of being dropped.

**Self-reply (follow-up on your own sent message):** detected via the authenticated `sendAs` email. Plain reply flips To to the first original recipient. Reply-all flips To to all original recipients. Cc is preserved from the original in both modes.

### Read

```bash
$CLI gmail list [--query "is:unread"] [--limit 20] [--account main] --compact
$CLI gmail get MESSAGE_ID --compact
$CLI gmail get-thread THREAD_ID --compact
$CLI gmail scan [--since "1d"] --compact          # no --limit or --query
$CLI gmail labels --compact
```

Response shapes (validated):

`list`: `{"messages":[{"id","threadId","from","to","subject","date","snippet","labelIds"}],"count","query"}`

`get`: `{"id","threadId","from","to","subject","date","snippet","labelIds","body"}`

From Elnora-AI/elnora-google-workspace, Apache-2.0.

More from Elnora-AI/elnora-google-workspace