Email Operations

Listing Emails

The list command shows your recent emails.

List Inbox

$ pontius list
 UID    FROM                      SUBJECT
 37801  [email protected]          Weekly standup notes
 37800  [email protected]       Your ticket has been updated
 37799  [email protected]       This week in tech
 37798  [email protected]          Re: Lunch tomorrow?

List from a Folder

Use --folder to list emails from a specific folder or Gmail label:

# Gmail labels
$ pontius list --folder "[Gmail]/Starred"
$ pontius list --folder "[Gmail]/Sent Mail"
# Custom labels/folders
$ pontius list --folder "Work/Projects"
$ pontius list --folder "billing"

Options

Option	Description
`--folder <name>`	List emails from specific folder (default: INBOX)
`--full`	Show full output without whitespace optimization

Searching Emails

The search command finds emails matching your query using IMAP search.

Basic Search

# Search for emails containing "invoice"
$ pontius search "invoice"
 UID    FROM                      SUBJECT                              DATE
 94570  billing.com               Your invoice is ready                2026-01-07
 94123  vendor.com                Re: Invoice #1234                    2026-01-05
# Search in a specific folder
$ pontius search "refund" --folder "support"
# Search archived emails
$ pontius search "contract" --folder "[Gmail]/All Mail"

# Search by sender
$ pontius search "meeting" --from "[email protected]"
# Search subject only (faster)
$ pontius search "urgent" --subject
# Combine filters
$ pontius search "project" --from "[email protected]" --subject

Date Range

Limit results to a specific time period:

# Last 7 days
$ pontius search "report" --days 7
# Last 30 days
$ pontius search "newsletter" --days 30
# Since a specific date
$ pontius search "contract" --since 2026-01-01

Search Options

Option	Description
`--folder <name>`	Search in folder (default: INBOX)
`--from <addr>`	Filter by sender email/domain
`--subject`	Search subject only (faster than full text)
`--days <n>`	Only last N days
`--since <date>`	Since date (YYYY-MM-DD format)
`--limit <n>`	Max results to return (default: 50)

AI-Powered Search

Search is especially powerful with AI assistants. Ask Claude to find all emails about a specific topic from the past week, then summarize them or draft responses.

Reading Emails

The read command displays the full content of an email.

$ pontius read 37801
From: [email protected]
To: [email protected]
Subject: Weekly standup notes
Date: Mon, 6 Jan 2026 09:30:00
Hey team,
Here are the notes from today's standup:
- Project Alpha: On track for Q1 release
- Bug fixes deployed to production
- New team member starting next week
Let me know if I missed anything.
Best,
Sarah

Reading from Folders

Use --folder to read emails from archived or labeled folders:

# Read from All Mail (archived emails)
$ pontius read 94570 --folder "[Gmail]/All Mail"
# Read from a custom label
$ pontius read 37801 --folder "support"

Read Options

Option	Description
`--folder <name>`	Read from specific folder (default: INBOX)
`--full`	Show raw HTML output without processing

Reply-To Header

If the email has a Reply-To header different from the From address, Pontius will show it. This is common with contact form submissions.

Replying to Emails

The reply command sends a reply to an email.

$ pontius reply 37801 "Thanks for the update. Everything looks good on my end."
Sent.

Reply Options

# Reply from an alias
$ pontius reply 37801 --from [email protected] "Thank you for contacting us..."
# Reply with CC
$ pontius reply 37801 --cc [email protected] "Adding Sarah to this thread..."

Option	Description
`--from <email>`	Send from a configured alias
`--cc <email>`	Add CC recipient(s)

Sending New Emails

The send command creates and sends a new email.

$ pontius send [email protected] "Meeting Request" "Hi, are you available for a call tomorrow at 2pm?"
Sent.

Send Options

# Send from an alias
$ pontius send --from [email protected] [email protected] "Subject" "Body"
# Send with CC
$ pontius send --cc [email protected] [email protected] "Subject" "Body"
# Send with BCC
$ pontius send --bcc [email protected] [email protected] "Subject" "Body"
# Send with attachment
$ pontius send [email protected] "Your Ticket" "See attached." --attach ~/Downloads/ticket.pdf
Sent with attachment: ticket.pdf (245 KB)
# Combine options
$ pontius send --from [email protected] --cc [email protected] [email protected] "Subject" "Body"

Option	Description
`--from <email>`	Send from a configured alias
`--cc <email>`	Add CC recipient(s)
`--bcc <email>`	Add BCC recipient(s)
`--attach <file>`	Attach a file (PDF, image, document, etc.)

Message Formatting

For multi-line messages, use literal newlines in quotes or heredocs in your shell:

$ pontius send [email protected] "Subject" "Line one.
Line two.
Regards,
Your Name"

Archiving Emails

The archive command moves emails to the archive (Gmail's All Mail).

# Archive single email
$ pontius archive 37799
Moved email 37799 to "[Gmail]/All Mail"
# Archive multiple emails
$ pontius archive 37798,37799,37800
Moved email 37798 to "[Gmail]/All Mail"
Moved email 37799 to "[Gmail]/All Mail"
Moved email 37800 to "[Gmail]/All Mail"
# Archive a range
$ pontius archive 37795-37800
Moved email 37795 to "[Gmail]/All Mail"
Moved email 37796 to "[Gmail]/All Mail"
Moved email 37797 to "[Gmail]/All Mail"
Moved email 37798 to "[Gmail]/All Mail"
Moved email 37799 to "[Gmail]/All Mail"
Moved email 37800 to "[Gmail]/All Mail"

Moving Emails

The move command moves emails to a folder or label.

# Move to a folder
$ pontius move 37801 "Work/Meetings"
Moved email 37801 to "Work/Meetings"
# Move multiple emails
$ pontius move 37798,37799 "billing"
Moved email 37798 to "billing"
Moved email 37799 to "billing"
# Move to Gmail system folders
$ pontius move 37801 "[Gmail]/Trash"
Moved email 37801 to "[Gmail]/Trash"

Folder Names

Use the exact folder name as shown by pontius folders. Gmail system folders are prefixed with [Gmail]/.

Unsubscribing from Newsletters

The unsubscribe command handles List-Unsubscribe headers automatically. When RFC 8058 one-click unsubscribe is supported, Pontius POSTs directly — no browser needed.

# One-click unsubscribe (RFC 8058)
$ pontius unsubscribe 37853
Attempting one-click unsubscribe...
Unsubscribed successfully (one-click)
# HTTPS fallback (opens browser)
$ pontius unsubscribe 37854
Opening unsubscribe page in browser...
https://newsletter.example.com/unsubscribe?token=abc123
# Mailto fallback (shows address)
$ pontius unsubscribe 37855
No automated unsubscribe available.
Send email to: [email protected]

How It Works

One-click (RFC 8058): If the sender supports List-Unsubscribe-Post, Pontius POSTs directly to the unsubscribe URL. Instant, no browser.
HTTPS link: If only an HTTPS unsubscribe URL is available, Pontius opens it in your default browser.
Mailto: If only a mailto link is available, Pontius shows the email address to send to.

Token-Optimized

Pontius only fetches the List-Unsubscribe headers — not the full email body. This keeps token usage minimal when your AI handles unsubscribe requests.

Tips for AI Integration

UIDs are stable: Email UIDs remain constant within a session, so your AI can reference them reliably.
Concise output: All commands produce minimal output to save tokens.
Bulk operations: Use comma-separated UIDs or ranges to minimize the number of commands needed.
Reply vs Send: For forwarded tickets, use send to the actual recipient rather than reply to the forwarder.

Email Operations

Listing Emails

List Inbox

List from a Folder

Options

Searching Emails

Basic Search

Search Filters

Date Range

Search Options

Reading Emails

Reading from Folders

Read Options

Replying to Emails

Reply Options

Sending New Emails

Send Options

Archiving Emails

Moving Emails

Unsubscribing from Newsletters

How It Works

Tips for AI Integration