---
version: 9
name: email_db
label: Email Database
description: Query, search, aggregate, and manage the user's email database. Use this tool to answer questions about emails, find messages by sender/domain/date/content, get statistics, and delete emails. The database is a local SQLite copy of the user's synced Gmail. All actions default to inbox scope — use folder parameter to query other folders like sent, spam, trash, or 'all' for everything.
language: typescript
inputs:
  action:
    type: string
    description: "Action to perform: query, search, stats, count, domains, senders, attachments, attachment-types, extract-attachment, delete"
  sql:
    type: string
    description: "Raw SQL query for the 'query' action. Only SELECT statements are allowed unless action is 'delete'."
    optional: true
  search:
    type: string
    description: "Search term for the 'search' action. Searches subject, from, and snippet fields."
    optional: true
  domain:
    type: string
    description: "Domain to filter by (e.g. 'newsletter.example.com') for search, count, or delete actions."
    optional: true
  sender:
    type: string
    description: "Sender email address to filter by for search, count, or delete actions."
    optional: true
  before:
    type: string
    description: "ISO date string — only include emails before this date."
    optional: true
  after:
    type: string
    description: "ISO date string — only include emails after this date."
    optional: true
  content_type:
    type: string
    description: "Attachment content type filter. Full MIME type (e.g. 'image/jpeg') or just the type prefix (e.g. 'image' matches all image types). Used with 'attachments' action."
    optional: true
  email_id:
    type: string
    description: "Email ID for extract-attachment action."
    optional: true
  attachment_idx:
    type: number
    description: "Attachment index (0-based) for extract-attachment action."
    optional: true
  folder:
    type: string
    description: "Gmail folder/label to scope results. Defaults to 'inbox'. Use 'all' for all folders. Common values: inbox, sent, spam, trash."
    optional: true
  limit:
    type: number
    description: "Maximum number of results to return. No limit by default — all results are returned. If a query could return a very large number of results, ask the user if they'd like to set a limit before running it."
    optional: true
---

# Email Database Tool

Query and manage the user's local email database (SQLite).

## Available Actions

- **query**: Run a raw SELECT query against the database. Use `sql` parameter.
- **search**: Full-text search across subject, from, and snippet. Use `search` parameter. Combine with `domain`, `sender`, `before`, `after` for filtering.
- **stats**: Get email statistics — total count, top domains, top senders, date range.
- **count**: Count emails matching filters (`domain`, `sender`, `before`, `after`).
- **domains**: List all sender domains with email counts, sorted by frequency.
- **senders**: List all senders with email counts, sorted by frequency.
- **attachments**: Search attachments by type, filename, sender, etc. Use `content_type` for type filtering (e.g. `image` for all images, `image/jpeg` for specific type). Combine with `domain`, `sender`, `before`, `after`, `search`.
- **attachment-types**: List all attachment content types with counts.
- **extract-attachment**: Extract an attachment file from the database and save it to ~/Downloads/. Requires `email_id` and `attachment_idx`. Use the `attachments` action first to find the email_id and idx. Output filename: `{YYYYMMDD}_{sender}_{email_id}_{idx}_{name}.{ext}` (e.g. `20250115_boss@company.com_abc123_0_invoice.pdf`).
- **delete**: Delete emails matching filters. Requires at least one of: `domain`, `sender`, `before`, `after`, or `sql` (with DELETE statement).

## Database Schema

```sql
emails (
  id TEXT PRIMARY KEY,
  integration TEXT,      -- source: 'gmail', 'outlook', etc.
  email_account TEXT,    -- which account: 'user@gmail.com'
  from_name TEXT,        -- sender display name
  from_address TEXT,     -- sender email (lowercase)
  from_domain TEXT,      -- domain extracted from sender
  to_address TEXT,
  cc TEXT,
  subject TEXT,
  date TEXT,             -- ISO 8601
  snippet TEXT,
  html TEXT,
  text_body TEXT,
  attachment_count INTEGER,
  read INTEGER,
  deleted INTEGER,
  labels TEXT            -- comma-separated label list (e.g. 'INBOX,UNREAD,CATEGORY_UPDATES')
)

attachments (
  email_id TEXT,
  idx INTEGER,
  filename TEXT,
  size INTEGER,
  content_type TEXT,
  content TEXT           -- base64-encoded binary content (use extract-attachment action to export)
)
```

## Examples

- Search for invoices (inbox only): `action: "search", search: "invoice"`
- Search sent emails for invoices: `action: "search", search: "invoice", folder: "sent"`
- Search all folders: `action: "search", search: "invoice", folder: "all"`
- Count emails from a domain: `action: "count", domain: "newsletter.com"`
- Delete all emails from a domain: `action: "delete", domain: "spam.com"`
- Top 10 domains: `action: "domains", limit: 10`
- Stats for spam folder: `action: "stats", folder: "spam"`
- List attachment types: `action: "attachment-types"`
- Find image attachments: `action: "attachments", content_type: "image"`
- Find PDFs from a sender: `action: "attachments", content_type: "application/pdf", sender: "boss@company.com"`
- Extract an attachment: `action: "extract-attachment", email_id: "abc123", attachment_idx: 0`
- Custom query: `action: "query", sql: "SELECT from_domain, COUNT(*) as n FROM emails GROUP BY from_domain HAVING n > 50 ORDER BY n DESC"`