email

name	email
description	Search and read Gmail messages. Use when looking up emails, reading email threads, or checking inbox labels.

Email (Read-Only)

Search and read Gmail messages using the gmail CLI.

Instructions

You are helping read Gmail data. Auth uses OAuth tokens stored at ~/.dots/sys/gmail/tokens/. Additional env vars (if any) are loaded from ~/.dots/sys/env.

Operations

# Search emails
gmail search "from:emily subject:kickoff"     # Search by sender and subject
gmail search "is:unread" --limit 10           # Recent unread
gmail search "after:2025/01/01 from:sarah"    # Date-filtered search

# Read a specific email
gmail read MESSAGE_ID                         # Read full email by ID

# List labels with message counts
gmail labels

# List configured accounts
gmail accounts

# Use a specific account
gmail search "budget" --account personal
gmail labels --account work

# Re-authenticate an account (opens browser for OAuth)
gmail auth personal

# JSON output
gmail search "quarterly review" --json
gmail accounts --json

Accounts

Run gmail accounts to see configured accounts with names and emails. The default account is marked with *.

Common Tasks

Find recent emails from someone

gmail search "from:emily" --limit 10

Read an email thread

# First search to find message IDs
gmail search "subject:technical kickoff" --limit 5
# Then read the specific message
gmail read MESSAGE_ID

Check unread count

gmail labels

Account Resolution

The CLI resolves accounts in this order:

1. --account NAME flag — uses ~/.dots/sys/gmail/tokens/NAME.json
2. Default account from ~/.dots/sys/gmail/accounts.json
3. First token file found in ~/.dots/sys/gmail/tokens/

Search Syntax

Gmail search supports standard Gmail query operators:

• from:sender — messages from a specific sender
• to:recipient — messages to a specific recipient
• subject:words — subject line search
• after:YYYY/MM/DD / before:YYYY/MM/DD — date range
• is:unread / is:starred — message state
• has:attachment — messages with attachments
• label:NAME — messages with a specific label
• in:inbox / in:sent — location filters

Capabilities

• Email search: Full Gmail query syntax with pagination
• Email reading: Full message content including headers, body text, and attachment metadata
• Label listing: All labels with message counts (total and unread)
• Account listing: Show all configured accounts with default marker

Troubleshooting

If a search or read fails with invalid_grant or Token has been expired or revoked, re-authenticate:

gmail auth ACCOUNT_NAME

This opens the browser for OAuth consent and saves the new token.

Limitations

• Read-only — Cannot send, draft, archive, or modify emails. For composing replies, draft the text in the conversation for manual copy/paste.
• Message body is truncated at 5000 characters