Agent skill

gmail

Read and search Gmail emails. Check inbox, search messages, and view email threads.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/gmail-tbroadley-dotfiles-e5385e20

SKILL.md

Gmail Integration

This skill provides read access to Gmail via the Gmail API.

Setup Required

Uses OAuth with persistent refresh token (same setup for Calendar, Gmail, Drive).

One-time setup:

bash
google-oauth-setup <path-to-client-secret.json>

See claude/skills/SETUP.md for detailed OAuth setup instructions.

Get Access Token (auto-refreshes):

bash
ACCESS_TOKEN=$(google-oauth-token)

Required header for all requests:

bash
-H "x-goog-user-project: ${GOOGLE_QUOTA_PROJECT}"

When to Use

Use this skill when the user:

  • Asks about their email or inbox
  • Wants to search for emails
  • Needs to find a specific message
  • Asks about recent emails
  • Mentions "Gmail" or email

API Endpoints

Base URL: https://gmail.googleapis.com/gmail/v1/users/me

List Messages

List Recent Messages:

bash
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

List with Query:

bash
curl -s -G "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
  --data-urlencode "q=is:unread" \
  --data-urlencode "maxResults=20" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Get Message

Get Full Message:

bash
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/{MESSAGE_ID}?format=full" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Get Metadata Only (faster):

bash
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/{MESSAGE_ID}?format=metadata" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Get Thread

Get Full Thread:

bash
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/threads/{THREAD_ID}?format=full" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Labels

List Labels:

bash
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/labels" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Profile

Get Profile Info:

bash
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/profile" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Gmail Search Query Syntax

Use the q parameter with Gmail search syntax:

Query Description
is:unread Unread messages
is:starred Starred messages
from:[email protected] From specific sender
to:[email protected] To specific recipient
subject:hello Subject contains "hello"
has:attachment Has attachments
filename:pdf Has PDF attachment
after:2024/01/01 After date
before:2024/01/31 Before date
newer_than:7d Last 7 days
older_than:1m Older than 1 month
label:work Has label
in:inbox In inbox
in:sent In sent

Combine queries: from:[email protected] subject:urgent after:2024/01/01

Common Workflows

Check Unread Emails

bash
ACCESS_TOKEN=$(google-oauth-token)

curl -s -G "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
  --data-urlencode "q=is:unread" \
  --data-urlencode "maxResults=10" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Search for Emails from Someone

bash
curl -s -G "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
  --data-urlencode "q=from:[email protected] newer_than:7d" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Read a Specific Email

bash
# Get message list first, then fetch specific message
MESSAGE_ID="18d1234567890abc"
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/${MESSAGE_ID}?format=full" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '{
    subject: .payload.headers[] | select(.name == "Subject") | .value,
    from: .payload.headers[] | select(.name == "From") | .value,
    snippet: .snippet
  }'

Get Recent Important Emails

bash
curl -s -G "https://gmail.googleapis.com/gmail/v1/users/me/messages" \
  --data-urlencode "q=is:important newer_than:1d" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Extracting Message Content

Email bodies are base64 encoded. To decode:

bash
# For simple text/plain messages
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/${MESSAGE_ID}?format=full" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq -r '.payload.body.data' | base64 -d

# For multipart messages, find the text/plain part
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/${MESSAGE_ID}?format=full" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq -r '.payload.parts[] | select(.mimeType == "text/plain") | .body.data' | base64 -d

Extracting Headers

Common headers to extract:

bash
curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/${MESSAGE_ID}?format=metadata" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.payload.headers[] | select(.name | IN("From", "To", "Subject", "Date"))'

Notes

  • Access tokens expire after 1 hour; use refresh token to get new ones
  • Message format options: minimal, metadata, raw, full
  • Gmail API has quotas (250 quota units/user/second)
  • The snippet field gives a preview without needing to decode the body
  • Thread IDs group related messages together

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results