gmail — Manual

Overview

IMAP/SMTP access to Gmail. Requires GMAIL_ADDRESS and GMAIL_APP_PASSWORD in .env. All list actions return messages newest first. Message IDs are IMAP UIDs — integers shown in list output.

Actions

send

Send a new email. body is HTML (wrap plain text in <p> if needed).

action=send  to="addr"  subject="..."  body="<p>Hello</p>"

list

Paginated inbox. offset skips N messages from the newest (default 0). query uses IMAP search syntax — see below.

action=list  max_results=10  offset=0  query='FROM "boss@company.com"'

Output per line: ● 4521 | From | Subject | Date (● = unread, ○ = read) If more messages exist, output ends with [N–M of total — use offset=K].

list_unread

All unread messages, no pagination (up to 100). Call this first to orient.

action=list_unread

read

Fetch full message by UID. Auto-marks as read. HTML bodies are converted to readable text; truncated at 5 000 chars.

action=read  uid="4521"

reply

Reply in the original thread. Only needs the UID and your HTML body — From, Subject, thread headers are set automatically.

action=reply  uid="4521"  body="<p>Got it, thanks.</p>"

IMAP query syntax (for list)

Criteria are ANDed when combined with a space.

Typical workflow

1. list_unread — see what's new
2. read uid="..." — read a specific message
3. reply uid="..." body="..." — respond in thread