Email Triage

Scan Joel's email inboxes (Front), triage conversations by importance, archive noise, and surface items needing attention. All operations use the joelclaw email CLI.

Canonical Email Interface

Front is canonical for all email triage in joelclaw.
Never use gog gmail for triage — bricks@aihero.dev, VIP threads, and all inboxes are in Front.
Use gog for Google Workspace operations (Calendar, Drive, Docs, etc.), not email triage.

Front Search API Reference

The search endpoint is GET /conversations/search/{url_encoded_query}. Results sorted by last activity date (not configurable).

Valid `is:` statuses

open, archived, assigned, unassigned, snoozed, trashed, unreplied, waiting, resolved

There is NO is:unread. Use is:unreplied for conversations where the last message was inbound.

Status conflicts (cannot combine):

archived ↔ open ↔ trashed ↔ snoozed (mutually exclusive)
assigned ↔ unassigned (mutually exclusive)

Date filters — UNIX TIMESTAMPS ONLY

before:<unix_seconds> — messages/comments created before this timestamp
after:<unix_seconds> — messages/comments created after this timestamp
during:<unix_seconds> — messages/comments on same day as timestamp

Front does NOT accept before:YYYY-MM-DD — always convert to unix seconds. The CLI --before and --after flags accept YYYY-MM-DD and convert automatically.

Recipient filters

from:<handle> — sender (email, social handle)
to:<handle> — recipient (includes to/cc/bcc)
cc:<handle>, bcc:<handle> — specific fields
recipient:<handle> — any role (from, to, cc, bcc)
Multiple same-type filters use OR logic: from:a@x.com from:b@x.com → either
Different filter types use AND logic: from:a@x.com to:b@x.com → both

Entity filters (use IDs, not names)

inbox:<inbox_id> — e.g. inbox:inb_41w25
tag:<tag_id> — e.g. tag:tag_13o8r1
assignee:<teammate_id> — e.g. assignee:tea_hjx3
participant:<teammate_id>, author:<teammate_id>, mention:<teammate_id>, commenter:<teammate_id>
contact:<contact_id>, link:<link_id>
custom_field:"<name>=<value>"

Free text

Bare words search subject + body. Phrases in quotes: "exact phrase".

No negation

Front search has no negation — no -from:, no NOT, no exclusion operators.

Max 15 filters per query.

CLI Commands

Scan inbox

joelclaw email inbox                          # default: is:open, 50 results
joelclaw email inbox -n 100                   # more results
joelclaw email inbox -q "is:open is:unreplied"  # awaiting reply
joelclaw email inbox --from notifications@github.com  # by sender
joelclaw email inbox --before 2026-02-01      # auto-converts to unix ts
joelclaw email inbox --after 2026-01-15       # auto-converts to unix ts
joelclaw email inbox --page-token "TOKEN"     # pagination (from previous response)

Flags can be combined:

joelclaw email inbox --from matt@totaltypescript.com --after 2026-02-01 -n 20

Archive single

joelclaw email archive --id cnv_xxx

Archive multiple by ID (fast, parallel, batched)

joelclaw email archive-ids --ids cnv_abc,cnv_def,cnv_ghi

Runs 10 concurrent requests. Best for triaging a page of results — grab the IDs of noise and blast them.

Archive bulk by query (dry-run by default)

joelclaw email archive-bulk -q "is:open from:notifications@github.com"           # dry run — shows count + sample
joelclaw email archive-bulk -q "is:open from:notifications@github.com" --confirm  # execute
joelclaw email archive-bulk -q "is:open from:notifications@github.com" --limit 100 --confirm  # batch size

Read a conversation

joelclaw email read --id cnv_xxx
joelclaw email read --id cnv_xxx --refresh   # bypass local cache

joelclaw email read uses a local thread + attachment cache (default TTL: 60 minutes). Cache path: ~/.cache/joelclaw/email/. Use --refresh to bypass cache and force a fresh fetch from Front.

Read output shape + jq patterns

joelclaw email read returns:

result.conversation: {id, subject, status, from: {name, email}, date, tags}
result.messages[]: {id, from: {name, email}, date, is_inbound, body_preview (or body), attachments[]}
result.attachment_summary: {total, cached, metadata_only, cache_errors}
result.cache: {hit, source, cache_path, age_seconds, ttl_seconds}

Message content is currently in body_preview, with a migration to body underway. Treat both as valid for backwards compatibility.

Correct extraction pattern (current field):

joelclaw email read --id cnv_xxx 2>&1 | jq '.result.messages[] | {from: .from.email, date: .date, body: .body_preview}'

Backwards/forwards-compatible extraction pattern:

joelclaw email read --id cnv_xxx 2>&1 | jq '.result.messages[] | {from: .from.email, date: .date, body: (.body // .body_preview)}'

List inboxes

joelclaw email inboxes

Triage Workflow

1. Load inbox state

joelclaw email inbox -n 50

Parse the JSON result. Each conversation has: id, subject, from (name + email), date, status, tags.

Useful follow-up queries:

joelclaw email inbox -q "is:open is:unreplied" -n 50   # awaiting reply
joelclaw email inbox --before 2026-01-01 -n 50          # old stuff to clean
joelclaw email inbox --from notifications@github.com    # CI noise check

2. Categorize using inference

Read each conversation and decide its category based on sender, subject, and context. Do NOT use hardcoded domain lists. Use judgment:

Reply needed — Real people expecting a response. Colleagues, collaborators, friends, business contacts with personal messages. Look for reply threads (Re:), questions, invitations to specific meetings, requests.
Read later — Interesting content worth saving. Newsletters Joel subscribes to intentionally (The Information, Astral Codex Ten, Lenny's Newsletter), industry news, technical deep-dives.
Actionable — Requires action but not a reply. Bills, security alerts, expiring trials, tax documents, delivery updates for real orders, calendar invites needing RSVP.
Archive — No value. Marketing spam, promotional offers, cold outreach, duplicate notifications, resolved alerts, automated reports nobody reads, vendor upsells.

3. Present triage summary

Organize findings for Joel. Lead with what matters:

## 🔴 Reply needed (N)
- **Name** — Subject (why it needs a reply)

## ⚡ Actionable (N)
- **Sender** — Subject (what action)

## 📖 Read later (N)
- **Source** — Subject

## 🗑️ Archive candidates (N)
- Count by type (e.g., "14 marketing, 8 CI failures, 5 duplicate notifications")

4. Execute decisions

Fastest path for noise: scan a page, collect noise IDs, use archive-ids:

joelclaw email archive-ids --ids cnv_aaa,cnv_bbb,cnv_ccc,cnv_ddd

For sender-based cleanup: use archive-bulk with from: filter:

joelclaw email archive-bulk -q "is:open from:notifications@github.com" --limit 100 --confirm

Rate limiting: Front allows ~50 req/s. If archiving large batches (>200), add pauses between batches or expect 429s. The CLI handles batching for archive-ids (10 concurrent), but archive-bulk iterates page-by-page and may hit limits on very large sets.

Read before deciding:

joelclaw email read --id cnv_xxx

Key Context

Joel has 8 Front inboxes across joel@egghead.io, joelhooks@gmail.com, joel@skillrecordings.com, joel@badass.dev, joel.hooks@vercel.com, LinkedIn, DMs, and Inngest
joelclaw email inboxes lists them all with IDs
Joel's teammate ID: tea_hjx3
The CLI handles Front API auth automatically via secrets lease front_api_token
Draft-then-approve for replies — never send directly
Front search results are eventually consistent — recently archived items may still appear in search for a few minutes
Pagination: responses include next_page_token when more results exist; pass via --page-token
[aih] subject prefix indicates AI Hero project threads via bricks@aihero.dev Google Group. Key participants: Alex Hillman (alex@indyhall.org), Matt Pocock (mattpocockvoice@gmail.com), Amy Hoy (team@stackingthebricks.com). Treat as VIP: always surface, never archive.

Signals for "Reply Needed"

These are heuristics, not rules. Use judgment for each:

Re: prefix + real person sender (not a bot/noreply)
[aih] prefix — AI Hero collaboration via bricks@aihero.dev (Alex Hillman, Matt Pocock, Amy Hoy). VIP: always surface, never archive.
Direct questions in subject line
Meeting invitations from known contacts
Threads where Joel was the last sender and someone replied
Slack notification summaries (may indicate missed conversations worth checking)

Signals for "Archive"

noreply@, no-reply@, notifications@ senders with no actionable content
Marketing subject patterns: "LAST chance", "% off", "deal", "unlock", "limited time"
Duplicate conversations (same subject from same sender — archive all but most recent)
Resolved monitoring alerts (RESOLVED in subject)
CI failure notifications older than 24h (stale — either fixed or won't be)
Cold outreach from unknown senders with sales language

Common Noise Senders (bulk-archive candidates)

These are historically high-volume, low-signal senders. Use archive-bulk with from: filter:

notifications@github.com        — CI failures, dependabot, PR notifications
alerts@alerts.betterstack.com   — resolved uptime alerts
no-reply@is.email.nextdoor.com  — neighborhood spam

Always dry-run first to verify the query matches what you expect.

email-triage