Email Read Skill | Agent Skills

Email Read

Read emails from Gmail inbox, sent folder, or any label via Gmail API

When to use

"check my email"
"what's in my inbox"
"read emails"
"any new messages?"
"check sent emails" / "did I send that email?"
"verify email was sent"
Morning briefing

Paths

| What | Path | |------|------| | Script | $GOOGLE_TOOLS_PATH/read_emails.py | | Token | $GOOGLE_TOOLS_PATH/token.json |

How to run

cd $GOOGLE_TOOLS_PATH

# Last 10 unread emails (default)
.venv/bin/python3 read_emails.py

# Last N unread emails
.venv/bin/python3 read_emails.py 20

# All emails (read + unread)
.venv/bin/python3 read_emails.py 10 all

# Custom query
.venv/bin/python3 read_emails.py 5 "from:client@example.com"
.venv/bin/python3 read_emails.py 10 "is:unread subject:invoice"
.venv/bin/python3 read_emails.py 5 "after:2026/02/01"

# SENT emails
.venv/bin/python3 read_emails.py 5 "in:sent"
.venv/bin/python3 read_emails.py 3 "in:sent to:alice@clientc.example.com"
.venv/bin/python3 read_emails.py 5 "in:sent after:2026/02/20"
.venv/bin/python3 read_emails.py 5 "in:sent subject:invoice"

Query examples

| Query | Description | |-------|-------------| | is:unread | Only unread (default) | | all | All messages | | from:team@yourcompany.com | From specific person | | subject:invoice | By subject | | after:2026/02/01 | After date | | is:starred | Starred messages | | has:attachment | With attachments | | label:important | By label | | in:sent | Sent emails | | in:sent to:user@example.com | Sent to specific person | | in:sent after:2026/02/20 | Recently sent | | in:drafts | Draft emails |

Important: When using in:sent, in:drafts, or label: queries, the script automatically removes the INBOX filter so results from other folders are returned correctly.

Full thread rule

IMPORTANT: When checking email about a specific person, company, or topic -- ALWAYS read the full thread (both inbox and sent). Otherwise you only see half the conversation.

# CORRECT: full thread with a person
.venv/bin/python3 read_emails.py 10 "from:client@example.com after:2026/02/01"
.venv/bin/python3 read_emails.py 10 "in:sent to:client@example.com after:2026/02/01"

# OR in one query (both sides):
.venv/bin/python3 read_emails.py 20 "{from:client@example.com OR to:client@example.com} after:2026/02/01"

When to apply:

"any updates from X?" -- read both sides
"did they reply to the invoice?" -- read both sent and inbox
Follow-up checks -- always full thread
If you only see inbox -- you don't know what we already sent

When NOT needed:

"show inbox" / "check email" -- just inbox
Morning briefing -- only new incoming

Output format

=== INBOX (N messages) ===        # or === SENT (N messages) ===

1. [NEW] Subject line
   From: Sender Name <email@example.com>
   Date: 2026-02-05 10:30
   Preview: First 100 chars of message...

2. Subject line (no [NEW] = already read)
   ...

OAuth scopes

Uses gmail.readonly scope from existing token.json.

Troubleshooting

| Problem | Solution | |---------|----------| | 401 Unauthorized | Refresh token: google-auth skill | | No messages | Check query syntax | | Token expired | Token auto-refreshes, but if fails run google-auth flow |

Related skills

email-send-direct - Send single email
email-send-bulk - Mass email sending
daily-briefing - Morning summary including inbox
google-auth - Auth troubleshooting

Agent Skills: Email Read

Install this agent skill to your local

Skill Files