email-read

$npx mdskill add aAAaqwq/AGI-Super-Team/email-read

Retrieve specific Gmail messages using advanced search queries.

  • Users verify sent emails, check unread messages, or find attachments.
  • The skill depends on the Gmail API for authentication and data access.
  • Agents filter results by date, sender, subject, or message status.
  • Output displays a list of email summaries matching the provided criteria.

SKILL.md

.github/skills/email-readView on GitHub ↗
---
name: email-read
description: Read inbox and sent via Gmail API
---
# 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

```bash
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.

```bash
# 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

More from aAAaqwq/AGI-Super-Team

SkillDescription
a-fund-monitor监控 A 股基金实时估值与盘后净值，自动判断交易日并生成提醒或分析。
add-leadAdd company/person/relationship to CRM
ads-agentAI-агент для управления Facebook рекламой. Вызывай для анализа, оптимизации, создания кампаний и отчётов.
afrexai-compliance-auditRun internal compliance audits against major governance and security
afrexai-personal-financeComplete personal finance system — budgeting, debt payoff, investing, tax optimization, net worth tracking, and financial independence planning. Use when managing money, building wealth, paying off debt, planning retirement, or optimizing taxes. Zero dependencies.
after-salesUse when managing post-purchase experience, building customer loyalty, or increasing repeat purchases
agent-contactsAI agent contacts — add, list, remove MCP contacts. Use when someone gives an agent URL, or when you need to view/remove contacts.
agent-model-switcher批量查看和切换子 agent 的模型配置，用于统一调整多 agent 的 provider/model 设置。
agent-patternsFormat SPAWN REQUEST messages to launch parallel agents, generate structured agent status reports, and define communication protocols within the sprint system. Use when the user needs to coordinate multiple agents, format spawn requests, produce agent reports, or establish inter-agent communication patterns.
agent-task-confirmUse when confirming whether a dispatched agent task was actually received, activated, and progressing after sessions_send or other task handoff actions.