aaaaqwq/email-read

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:[email protected]"
.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:[email protected]"
.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:[email protected] | 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:[email protected] | 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:[email protected] after:2026/02/01"
.venv/bin/python3 read_emails.py 10 "in:sent to:[email protected] after:2026/02/01"

# OR in one query (both sides):
.venv/bin/python3 read_emails.py 20 "{from:[email protected] OR to:[email protected]} 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 protected]>
   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