google-gmail

Files (1)

• SKILL.md

SKILL.md (first lines)

Drive Gmail via `curl + jq`. The user's OAuth bearer token is in
`$GOOGLE_GMAIL_TOKEN`; every call needs it as
`Authorization: Bearer $GOOGLE_GMAIL_TOKEN`. At minimum the token
carries `gmail.readonly` plus the identity scopes
(`openid email profile`); if the user opted in to write at install
time it also carries `gmail.modify` (label / archive / trash) and/or
`gmail.send` (compose + send). Always assume the narrowest scope
until a write actually fails — don't ask Google for new scopes from
here.

The Gmail API returns standard JSON; failures surface as
`{"error": {"code": 401|403|..., "message": "..."}}` — show that
error verbatim. `401` means the token expired (re-install). `403
insufficientPermissions` means the user didn't grant the write scope
this call needs — explain which scope is missing and suggest
re-installing the connector with the matching write box checked.

**Before any destructive write** (trashing a thread, sending an email)
show the user the exact target / draft and ask them to confirm. Don't
fan out across many messages without an explicit go-ahead.

**Always start with `users/me/profile`** to confirm the connection works
AND learn which Gmail account you're operating against. Mailbox payloads
can be huge — fetch metadata first, only `format=full` when the user
actually wants the body of a specific message.

## Optional: Google Workspace CLI (`gws`) for outbound mail

[`gws`](https://github.com/googleworkspace/cli) is Google's official CLI
(not officially supported — community-maintained on the `googleworkspace`
org). It dynamically builds its command surface from Google's Discovery
Document, exits non-zero on API errors, and ships hand-crafted helper
commands (prefixed `+`) that handle the message-encoding boilerplate.

**Use `gws` for sending mail.** The Gmail REST API requires every
outbound message to be a fully-formed RFC 822 message, base64url-encoded
into a `raw` field, with reply / forward threading carried in
`In-Reply-To` / `References` / `threadId`. The `+send / +reply /
+reply-all / +forward` helpers do all of that for you. **For everything
else** (read, search, labels, attachments) `gws` and curl are equivalent,
so the curl recipes below are usually shorter — stay on those.

### Install

```sh
npm install -g @googleworkspace/cli   # or: brew install googleworkspace-cli
# Pre-built binaries also at https://github.com/googleworkspace/cli/releases
gws --version
```

### Auth

`gws` reads its OAuth bearer token from the `GOOGLE_WORKSPACE_CLI_TOKEN`
environment variable. The Gmail token used in this skill is in
`$GOOGLE_GMAIL_TOKEN`, so re-export it once at the top of every shell
block that calls `gws`:

```sh
export GOOGLE_WORKSPACE_CLI_TOKEN="$GOOGLE_GMAIL_TOKEN"
```

You can confirm the active account with `gws gmail users getProfile
--params '{"userId":"me"}'`.

### Send / reply / forward

```sh
# New message
gws gmail +send \
  --to alice@example.com \
  --cc team@example.com \
  --subject "Q1 status" \
  --body "Numbers attached."

# Reply (handles threadId, In-Reply-To, References automatically;
# To is the original sender, Subject gets the "Re: " prefix)
gws gmail +reply --message-id MSG_ID --body "Thanks — looks good."

# Reply-all
gws gmail +reply-all --message-id MSG_ID --body "+1"

# Forward to new recipients (preserves the original message body
# inline; original headers are summarised in the forward block)
gws gmail +forward --message-id MSG_ID --to bob@example.com
```

Each helper exits with a non-zero status and a JSON error on stderr if
Google rejects the request — surface that error verbatim. `+send` /
`+reply` need the `gmail.send` scope; if the user only granted
`gmail.readonly` you'll see `403 insufficientPermissions` and should ask
them to re-install the connector with the send box checked.

All the read / list / search / label / attachment recipes below are
intentionally **not** rewritten to `gws` — a one-line `curl ... | jq` is
shorter and easier to compose with shell pipelines.

## Recipes

### Verify auth (always run first)

```sh
curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
  "https://gmail.googleapis.com/gmail/v1/users/me/profile" \
  | jq '{email: .emailAddress, totalMessages, totalThreads, historyId}'
```

### List recent unread inbox

```sh
curl -sS -H "Authorization: Bearer $GOOGLE_GMAIL_TOKEN" \
  --get "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
  --data-urlencode 'q=is:unread in:inbox newer_than:7d' \
  --data-urlencode 'maxResults=20' \
  | jq '.messages // [] | .[]'
```

**Always default `.messages` to `[]`** — Gmail's `messages.list` omits the
field entirely when there are zero matches (the response is just
`{"resultSizeEstimate": 0}`), so a bare `.messages[]` will crash jq

From AceDataCloud/Skills, Apache-2.0.

More from AceDataCloud/Skills