Hey

/hey - HEY Email Workflow Command

CLI for HEY: mailboxes, labels, collections, email threads, contacts, replies, compose, calendars, todos, habits, time tracking, and journal entries.

Agent Invariants

MUST follow these rules:

1. Choose the right structured output — use --jq '<expression>' to filter or extract fields and --json for the full response. Never pipe to an external jq; --jq is built in and implies --json.
2. Reuse stored authentication — run the requested data command; it uses stored credentials and refreshes expiring OAuth tokens automatically. If it returns an auth error, follow the one-command macOS/Codex retry in Authentication before you report the task as blocked. Use hey auth status --json when an explicit authentication check is needed (it reports stored credentials and does not contact HEY). Never run hey auth login unattended; use it only for interactive recovery with the user present.
3. HTML output — --html writes the original HTML of hey thread read, hey journal read, and a contact's private note (hey contact show or hey contact note show) to a pipe or file; a terminal is refused
4. Linked mail accounts share one login — use hey account list --json, then --account <id|all> when a task must target one account
5. Local HEY configuration requires human trust — never run hey config trust-local without the user's explicit approval

Output Filtering

--jq filters the full JSON success envelope, so result data is under .data. String results print as plain text; objects and arrays print as formatted JSON. Use --quiet --jq when the expression should run against result data directly. Errors retain their complete structured envelope. Commands with dedicated raw output (auth token, shell-completion generate, setup, skill, tui, --version, and timetrack export without --output) reject --jq. hey watch writes one raw JSON event per line with no envelope and does not apply --jq.

hey box list --jq '.data[] | {id, name}'
hey search "quarterly planning" --jq '.data[].topic_id'
hey box list --quiet --jq '.[].name'

An empty result is an empty array rather than null, so .data[] is safe to run against a listing that found nothing.

For the two commonest shapes there is no need for an expression at all: --ids-only prints one ID per line and --count prints a bare number on stdout. Both answer for what was read, which is the first page unless --all (or --limit) reads more, and not every listing warns on stderr that more pages exist — hey screener list --count is the exception and counts the whole queue. Both need list data, so they work on the listings: every list command, the thread listings (hey box view, hey label view, hey collection view, hey set-aside view, hey set-aside group view, hey bundle view, hey contact threads, hey bubble list), hey workflow view, hey search, hey screener history, hey event day, hey event week, hey timetrack categories, hey attachment list and hey thread read (its entries, read from the index without fetching bodies). On the thread listings they count and list the postings, not the box, label or contact around them.

Quick Reference

Decision Trees

Reading Email

Want to read email?
├── Which mailbox? → hey box list --json
├── List emails in box? → hey box view <name|id> --json
├── List labels or labeled email? → hey label list --json / hey label view <label_id> --json
├── Add, create, or remove a label? → hey label add|create|remove
├── List collections or collection threads? → hey collection list --json / hey collection view <collection_id> --json
├── Create, update, add to, or remove from a collection? → hey collection create|update|add|remove
├── See Set Aside with its groups? → hey set-aside view --all --json / hey set-aside group list --json
├── Group, regroup, or ungroup Set Aside threads? → hey set-aside group create|add|remove (delete sends the group's threads to Previously Seen)
├── Search threads and messages? → hey search <query> --json
├── Need available refinements? → hey search filters --json
├── List or view contacts? → hey contact list --json / hey contact show <contact_id> --json
├── Find a contact by email? → hey contact list --all --jq (see Contacts)
├── Every thread with a contact? → hey contact threads <contact_id> --json
├── Change where a contact's future email arrives? → hey contact deliver <contact_id> --to imbox|feed|papertrail|screened-out
├── A row with kind "bundle"? → hey bundle view <box_item_id> --json (its unseen threads)
├── Read full thread? → hey thread read <topic_id> --json
├── Get a sharing link? → hey share <topic_id>
├── Turn off the sharing link? → hey unshare <topic_id>
├── Mark as seen? → hey seen <box_item_id>
├── Mark as unseen? → hey unseen <box_item_id>
├── Move to another box? → hey move <box_item_id> --to <box>
├── Remove or unmark Reply Later? → hey move <box_item_id> --to imbox
├── Move to Trash? → hey trash <box_item_id>
├── Mark as spam? → hey spam <box_item_id>
├── Ignore future activity? → hey ignore <box_item_id>
├── Stop ignoring? → hey stop-ignoring <box_item_id>
├── Who is waiting to be screened? → hey screener list --json
├── Screen a sender in or out? → hey screener approve|deny <clearance_id>
└── Launch interactive UI? → hey tui

Sending Email

Want to send email?
├── Reply to thread? → hey reply <topic_id> -m "message"
│   ├── Open editor? → hey reply <topic_id> (with no message: $EDITOR at a terminal, otherwise stdin)
│   └── Attach files? → add --attach ./report.pdf (repeatable)
├── Reply to many threads at once? → hey bulk-reply preview <box_item_id>... first, then send
│   └── Sent by mistake? → hey bulk-reply undo <delivery_id> (while the window is open)
├── Forward latest message? → hey forward <topic_id> --to <email>
│   └── Add a note? → add -m "note"
├── Compose new? → hey compose --to <email> --subject "Subject" -m "Body"
│   ├── With files? → add --attach ./report.pdf (repeatable; body is optional)
│   ├── With CC? → add --cc <email>
│   └── With BCC? → add --bcc <email>
├── List files in a thread? → hey attachment list <topic_id> --json
│   └── Save one? → hey attachment save <attachment_id> [--output <path>]
├── Draft instead of sending (human reviews in HEY)? → add --draft to compose or reply; the answer carries the draft id
│   ├── Read it back? → hey draft show <draft_id> --json
│   ├── Change it? → hey draft edit <draft_id> --subject/--to/--cc/--bcc/-m (flags replace; omitted fields are kept)
│   ├── Deliver it? → hey draft send <draft_id> (recipients required)
│   └── Discard it? → hey draft delete <draft_id>
└── Check drafts? → hey draft list --json

In JSON output, a send (compose, reply, forward, draft send) answers with the new message's id and its thread's topic_id — use topic_id with hey thread read. delayed: true means Undo Send is still holding it, and until it goes out HEY leaves it out of its thread: hey thread read <topic_id> shows the thread without it, or answers not_found for a thread it started — wait and read again rather than treating the send as lost. A field HEY's answer leaves out is left out, never guessed. A send HEY refused — usually the account's sending limit — fails with not_delivered (exit 7): HEY kept it as a draft, named by draft_id in the error, and hey draft send <draft_id> sends it later. Do not resend the message; that makes a second draft.

Managing Todos

Want to manage todos?
├── List todos? → hey todo list --json
├── Add todo? → hey todo add "Task description"
├── Complete? → hey todo complete <id>
├── Uncomplete? → hey todo uncomplete <id>
└── Delete? → hey todo delete <id>

Resource Reference

Email - Boxes

hey box list --json                          # List all mailboxes
hey box view imbox --json                    # List emails in Imbox (by name)
hey box view 123 --json                      # List emails in box (by ID)
hey box view imbox --page next-cursor --json # Continue from an earlier listing

Box names: imbox, feed, papertrail, setaside, replylater, bubbleup — or the kind (feedbox, trailbox, asidebox, laterbox, bubblebox) or display name ("Paper Trail", or a name the user gave the box), in any case. hey search --in and hey move --to take the same spellings, but not every box: hey search --in takes only imbox, feed and papertrail (plus trash), and hey move --to takes a box ID or any box but bubbleup (use hey bubble up). A name that matches no box is not_found in hey box view and hey move --to, and a usage error in hey search --in, which answers every box it cannot narrow to that way. Trash is not a box: search it with hey search --in trash and move threads there with hey trash.

Response format: hey box view --json returns the box itself — id, kind, name, app_url, next_history_url, next_page — with a postings array of the email threads in it. Each posting has id (box item ID), topic_id (thread ID), kind (bundle for a bundle row), name (subject), created_at and app_url; a thread row also has contacts, summary and visible_entry_count. seen is present only when true — an unseen posting omits it, so test .seen != true. Use id for the box item commands (see the ID note under Threads) and topic_id for hey thread read, hey reply, hey forward, hey share and hey attachment list.

Unmatched IDs are not reported. HEY checks only that some box item ID in a call is yours. hey trash, hey spam, hey label add|remove|create and hey bubble up|pop answer not_found only when none match; hey seen, hey unseen, hey move, hey ignore, hey stop-ignoring and hey set-aside group create|add|remove never check (group create with no matching ID leaves an empty group). Every ID that does match is changed, so a mixed batch is a partial success reported as a whole one, a typo is silently skipped, and a topic_id that happens to equal one of your box item IDs acts on that unrelated thread (the reverse, a box item ID given to hey thread read, can likewise read an unrelated thread). Confirm rather than trust the envelope: hey box view <box> --json --all --jq '{notice, next_page: .data.next_page, match: [.data.postings[] | select(.id == <id>) | {id, topic_id, seen}]}' for a mark, or the destination box for a move. --all reads up to 101 pages; an empty match with next_page still set means the box is larger than that, so continue with --page <next_page> rather than calling it a non-match.

A posting whose kind is bundle rolls one sender's mail into a single row and can omit topic_id: a bundle names its sender rather than a thread, and its name joins the bundled subjects with •. It carries a topic_id only while it holds exactly one unseen thread, and hey thread read reads that thread as usual. Never substitute the bundle row's id for a thread (hey thread read <id> answers not_found, with a hint naming the bundle). Instead, hey bundle view <id> lists the bundle's unseen threads, each with its topic_id, and answers the bundled contact; hey contact threads <contact_id> lists every thread with that sender, seen and unseen — the only place a bundle's mail is listed once it has been read through. hey move refuses a bundle row; change grouping with hey contact bundle|unbundle <contact_id>.

next_page is the cursor --page takes, and it is the cursor inside next_history_url — --page accepts either. --all reads up to 101 pages; if next_page is still set, continue with --page.

--ids-only and --count work here too, and answer for the postings: one box item ID per line, or how many threads were read.

Email - Labels

hey label list --json                         # List labels and stable IDs
hey label view 789 --all --json                # List every thread with a label
hey label add 12345 --to 789                   # Add an existing label
hey label create "Travel receipts" 12345       # Create and add a label
hey label remove 12345 --from 789              # Remove one label
hey label remove 12345 --from all              # Remove every label

Label mutations take box item IDs from hey box view, hey label view, or hey search results that carry an id. Label IDs come from hey label list. hey label view returns next_page and total_count; pass --page <next_page> to continue or --all to fetch every page. label create files at least one thread as it creates the label, so it needs one or more of your box item IDs; a name you already use (in any case) is refused — use label add for an existing label.

Email - Collections

hey collection list --json                                 # List collections and stable IDs
hey collection view 321 --all --json                        # List every thread in a collection
hey collection create "Kitchen remodel" --summary "Plans and decisions"
hey collection update 321 --name "Kitchen renovation"
hey collection add 987 --to 321                             # Add a topic ID
hey collection remove 987 --from 321                        # Remove a topic ID

Collection IDs come from hey collection list. hey collection view returns posting id, thread topic_id, next_page, and total_count; pass --page <next_page> to continue or --all to fetch every page. Collection membership commands take topic_id. Creating a collection confirms the mutation, and listing collections provides its ID for later commands.

Email - Set Aside groups

hey set-aside view --all --json                # Set Aside threads, each with box_group_id when grouped
hey set-aside group list --json                # Groups with thread_count
hey set-aside group view 42 --all --json       # Threads in one group; pages like a box
hey set-aside group create 12345 67890         # New group from box item IDs; answers the group id
hey set-aside group add 12345 --to 42          # File threads into a group (moves them out of another)
hey set-aside group remove 12345               # Ungroup; threads stay in Set Aside
hey set-aside group delete 42                  # Dissolve the group; its threads go to Previously Seen

Groups have no name in HEY: a group is its ID and the threads in it. Group commands take posting id values (box item IDs), not topic_id. HEY's group index answers IDs alone, so group list reads each group once for its count; group view returns next_page and total_count and takes --page and --all. HEY removes a group itself once its last thread leaves, so group view or group delete on it answers not_found. group create and group add move threads into Set Aside if they are elsewhere and mark them seen, which also clears a bubble-up. To clear an overflowing Set Aside without losing threads, prefer group create/group add over group delete: deleting a group moves its threads to Previously Seen in the Imbox.

Email - Workflows, clips and snippets

hey workflow list --json                                   # Workflows and their IDs
hey workflow view 123 --json                               # Stages, in position order, with IDs
hey workflow add 501 --to 123 --stage 456                  # Put threads (topic IDs) in a stage
hey workflow move 501 --workflow 123 --to 789              # Move them to another stage
hey workflow remove 501 --from 123                         # Take them out of the workflow
hey workflow create "Hiring"                               # Also: update <id> --name, delete <id>
hey workflow stage create 123                              # Adds an Untitled stage; rename with stage update
hey workflow stage update 123 456 --name "Interviewing"
hey clip create 987 --content "The launch moves to Wednesday."  # Save a passage from an entry
hey clip delete 44
hey snippet create --name "Scheduling reply" --content "Tuesday works for me."
hey snippet update 44 --content "Wednesday works for me."
hey snippet delete 44

Workflow membership commands take topic_id. hey clip create takes an entry ID — an entry's id from hey thread read — and the passage must appear in that message's text; hey clip list reads only the newest page of clips.

Email - Search

hey search "quarterly planning" --json         # Free-text search
hey search --from jane@example.com --date last_30_days --json  # Refined search
hey search --subject invoice --attachment pdfs --all --json    # Search up to 100 pages
hey search filters --json                      # Available box, date, label, and attachment values

Search refinements are --required, --any, --none, --exact, --from, --to, --subject, --date, --in, --label, and --attachment. --page selects one result page; --all fetches up to 100 pages from that point onward. When the cap is reached, the response notice provides the next --page value for continuation.

--in, --date, --label and --attachment accept only the values hey search filters lists: boxes are imbox, feed, papertrail, trash (the kind or display name of one of those three boxes works too, such as trailbox or a name the user gave the Imbox, at the cost of one box list read for an unfamiliar name); dates are last_7_days, last_30_days, last_90_days or a year (hey search filters lists 2020 to this year; the CLI refuses anything but 20xx); attachment kinds are any, images, pdfs, calendar_invites, documents, spreadsheets, presentations, media, zip_files. The kinds are plural — --attachment pdfs, not pdf. An unrecognized --in, --date or --attachment is refused as a usage error naming the values it accepts, before any search is sent — for --in that includes Set Aside, Reply Later, Bubble Up and a name no box has, never not_found; --label is not checked, so read hey search filters when unsure of a label.

Response format: data contains one item per matching thread. Each result has id (box item ID for organization actions), topic_id (thread ID for hey thread read, hey reply, and hey forward), subject, updated_at, and messages containing the matching message IDs, senders, dates, and summaries. A result omits id when you have no box item for its thread.

Contacts

hey contact list --json                       # List contacts
hey contact list --page 2 --json              # List another page
hey contact list --all --jq '.data[] | select(.email_address == "jane@example.com") | .id'  # Find a screened-in contact by email
hey contact show 12345 --jq '.data | del(.postings)'  # Details, aliases, and private note, without its threads
hey contact threads 12345 --all --json        # Every thread with the contact, seen and unseen
hey contact add --name "Jane Doe" --email jane@example.com
hey contact add --name "Jane Doe" --email jane@example.com --alias jane.doe@example.org
hey contact update 12345 --name "Jane Dawson"
hey contact update 12345 --alias=              # Clear aliases
hey contact hide 12345                         # Hide from lists and autocomplete
hey contact show-again 12345                   # Reverse hiding
hey contact deliver 12345 --to feed            # Route future email to The Feed
hey contact deliver 12345 --to screened-out    # Block future email from an external contact
hey contact bundle 12345                       # Group this contact's mail into one row
hey contact unbundle 12345                     # List this contact's mail separately
hey contact note show 12345 --json
hey contact note show 12345 --jq '.data.note_markdown'  # The note as Markdown; set it back only if note_markdown_lossless is true (see below)
hey contact note set 12345 "Prefers email"
echo "Prefers email; call only for urgent deliveries" | hey contact note set 12345
hey contact note set 12345 --note-html "<p><strong>Prefers email</strong></p>"
hey contact note delete 12345

hey contact list returns each contact's ID, name, primary email address and update timestamp. It lists only non-HEY senders you have screened in: other HEY users, senders still in (or denied by) The Screener, aliases and hidden contacts are left out, so an address missing there does not mean HEY has no contact for it. It has no search: to find a contact by email, read every page with --all (up to 100 pages; the notice names the --page to continue from) and filter with --jq as above. That matches primary addresses only — a contact's aliases are on hey contact show.

hey contact show adds aliases, screening status, the private note, and postings: a page of the contact's threads, which can run to tens of kilobytes. Drop it with --jq '.data | del(.postings)', read just the note with hey contact note show, or page through every thread with hey contact threads. Contact updates preserve omitted fields. Supplying --alias replaces the complete alias list, and --alias= clears it.

HEY hides contacts instead of permanently deleting them. A hidden contact leaves contact lists, autocomplete, and search results while remaining available by ID; show-again reverses the action. A contact that is hidden, an alias, or another HEY user cannot be edited: contact update, contact note set and contact note delete answer not_found.

hey contact deliver takes a contact ID from contact data — never substitute an email address, clearance ID, box item ID, or box ID. Its four exact destinations are imbox, feed, papertrail, and screened-out. Imbox removes a custom box preference; selecting a box does not approve a contact that is already Screened Out. Screened Out is the deny/blocking choice and applies only to external email contacts. Selecting Feed removes an existing bundle because HEY cannot keep a Feed-designated contact bundled; Imbox and Paper Trail preserve eligible bundles. The command is write-only: HEY does not expose the current setting as structured data, and existing mail may move asynchronously after success.

Bundling groups a contact's mail into one row without merging or deleting the underlying threads; unbundle lists those threads separately again. HEY bundles only a contact with no box preference or one sent to the Paper Trail; for any other, bundle answers success and changes nothing.

A contact note is written whole. hey contact note set replaces the entire note — there is no append — so to add a detail, read the note, change it, and write all of it back. It takes Markdown — positional, --note, stdin, or $EDITOR (which opens on the existing note, and is refused when note_markdown_lossless is false) — or raw HTML with --note-html; an empty note is refused, and hey contact note delete clears one without touching the contact. hey contact note show --json answers note (HEY's plain text, which loses formatting: bold is dropped, list items become •), note_html (the HTML as HEY serves it), note_markdown, and note_markdown_lossless. When note_markdown_lossless is true, note_markdown holds everything in the note and note set writes it back as the same note, so add to the Markdown. The read checks the flag itself and fails when it is false, so nothing is written:

note=$(hey contact note show 12345 --jq 'if .data.note_markdown_lossless then .data.note_markdown else error("note_markdown would drop part of this note: change note_html with --note-html") end') &&
  printf '%s\n\nMoved to the Lisbon office in March.\n' "$note" | hey contact note set 12345

When it is false, the note holds an attachment or other markup Markdown cannot carry, and setting Markdown would drop it. Add to the HTML instead — --note-html takes off the wrapper HEY serves the note in, so this does not nest:

note=$(hey contact note show 12345 --jq '.data.note_html') &&
  hey contact note set 12345 --note-html "$note<p>Moved to the Lisbon office in March.</p>"

Keep the &&: a failed read must not go on to write. The read and the write are not atomic — a save by someone else in between is lost — so write straight after reading.

Notes are private to the HEY account that holds the contact, so they are reached only through the user's own login. With linked accounts, --account <id> (from hey account list) selects whose contacts a command reads and writes.

Email - Threads

hey thread read <topic_id> --json                 # Read full email thread
hey thread read <topic_id> --html > thread.html  # Original HTML, to a file or pipe
hey thread read <topic_id> --allow-partial --json # Accept a thread that could only be read in part
hey share <thread_id>                         # Get a sharing link
hey unshare <thread_id>                       # Turn off the sharing link

hey thread read returns every entry in the thread, oldest first. Each entry's body is Markdown, converted from HEY's Trix HTML at the edge, so headings, lists, quotes, tables and code survive and links keep their URLs — read it as structure rather than as flattened text. creator is the entry's author — the external sender for inbound mail, your own contact for mail you sent. sender appears only on a hydrated message you sent from a different address (an alias, custom domain or external account); use sender.email_address for its From, and creator.email_address otherwise. An entry whose message was read also carries recipients, with to, cc and bcc contact lists; a known-empty line is [], while an entry whose message was not hydrated omits the object. In JSON, an inbound entry also carries received_via: every exact account address HEY recorded it arriving through, including aliases and plus tags. These delivery records are distinct from visible To/CC/BCC recipients. Each one's resolved contact is optional; received_via is omitted for sent/generated messages and when the message was not hydrated. --html returns the original body HTML framed by From, To, CC and BCC header rows, and is refused on a terminal — redirect it. A thread that could only be read in part is refused unless --allow-partial is given, and then the notice says what is missing. Use hey reply to have HEY work out reply addressing. An entry's kind is message for mail; comment (a note) and access_notice (a share notice) are internal to the thread and were never emailed — --markdown, styled and --html output label them so.

hey share returns a URL that shows the entire thread and future emails or replies sent to it. Anyone with the link can open it. hey unshare turns off the sharing link.

ID note: Every email thread has two IDs: an id (its box item ID) and a topic_id (its thread ID). hey seen, hey unseen, hey move, hey label add, hey label remove, hey trash, hey spam, hey ignore, hey stop-ignoring, hey bubble up|pop, hey set-aside group, hey bulk-reply and hey bundle view expect id. hey thread read, hey share, hey unshare, hey attachment list, hey reply, hey forward, hey compose --thread-id, hey collection add|remove, and hey workflow add|move|remove expect topic_id. Passing the wrong one is not redirected: depending on the command it answers not_found, is silently skipped, or acts on an unrelated thread whose ID happens to match — see "Unmatched IDs are not reported" under Boxes.

hey box view --json, hey label view --json, hey collection view --json, hey bundle view --json, hey contact threads --json and hey search --json all carry both, with two exceptions: a bundle posting can omit topic_id (see the Boxes section), and a search result omits id when you have no box item for its thread, so it cannot be used with the box item commands above.

Email - Attachments

hey attachment list <topic_id> --json               # List files in every message
hey attachment save 67890:1                    # Save using a returned ID
hey attachment save 67890:1 --output ./reports # Save into ./reports if that directory exists
hey attachment save 67890:1 --output ./report.pdf --force

Direct attachment IDs combine the message ID and position, so 67890:1 identifies the first direct attachment in message 67890. Named downloadable files inside embedded HTML, including named inline images, use opaque IDs scoped to their message. Pass the ID returned by hey attachment list to hey attachment save. Saving uses the original filename unless --output names a destination; --output is a directory only if one already exists there, otherwise it is the file name. Existing files are preserved unless --force is set.

Email - Reply, Forward & Compose

hey reply <topic_id> -m "Friday works for me — I'll send an agenda."  # Inline message
hey reply <topic_id>                          # $EDITOR at a terminal; otherwise the body is read from stdin
hey reply <topic_id> --to support@example.com -m "The replacement is on the way."
hey reply <topic_id> --to support@example.com --replace-recipients --dry-run --json
hey reply <topic_id> -m "Here is the wiring diagram." --attach ./diagram.png
hey forward <topic_id> --to alice@example.com                 # Forward the latest message
hey forward <topic_id> --to alice@example.com -m "Please review before Thursday."
hey compose --to alice@example.com --subject "Lunch plans"    # $EDITOR at a terminal; otherwise stdin
hey compose --to alice@example.com --subject "Lunch plans" -m "Are you free Friday?"
hey compose --to alice@example.com --subject "Q3 revenue report" --attach ./report.pdf  # No body text
hey compose --to alice@example.com --subject "Q3 revenue report" -m "The numbers are attached." --attach ./report.pdf --attach ./chart.png
hey compose --to alice@example.com --cc bob@example.com --bcc carol@example.org --subject "Kitchen remodel timeline" -m "Cabinets land the week of the 14th."
hey compose --thread-id 12345 -m "Confirmed — see you then."  # Reply into an existing thread (no subject: it carries the thread's)
hey compose --to alice@example.com --subject "Sprint recap" -m "We **shipped** the pagination fix."
hey compose --to alice@example.com --subject "Newsletter draft" --message-html "<h1>March</h1><p>What we shipped.</p>"

hey reply answers the thread's latest emailed message, as HEY's web app does. A note (kind: "comment") or share notice (kind: "access_notice") is internal: visible to everyone with access to the thread, never emailed, and never what a reply or hey forward answers; a thread with nothing else is refused. HEY addresses the reply the way its own web app does: everyone that entry was addressed to, plus whoever wrote it, on the To line, minus your own addresses. If HEY's prefill is unavailable or names no one (a thread with only yourself), a send falls back to the message's own recipients, which can include you. Repeatable --to, --cc and --bcc flags add or move explicit recipients. Use --replace-recipients to discard HEY's prefill. Run --dry-run --json first when an agent changes the envelope; it does not read the original message body and reports the resolved sender and final recipients without sending. If HEY's envelope prefill is unavailable, use --replace-recipients with explicit addresses because a dry run will not guess the original lists. A reply HEY cannot address is refused unless an explicit recipient makes it addressable.

Message bodies, drafts, journal entries, snippets and contact notes are Markdown by default — -m, --content, --note, positional content, stdin, and $EDITOR alike — and are converted to rich text on the way out (clip passages, event notes and time track notes are plain text). To send raw HTML instead, use the flag's HTML twin: --message-html on compose, reply, forward, draft edit and bulk-reply send; --content-html on journal write and snippet create/update; --note-html on contact note set. Each pair is mutually exclusive. --content-html and --note-html take off the <div class="trix-content"> wrapper HEY serves journal entries, snippets and notes in, so HTML read back can be written again without nesting. A fenced code block's language (```ruby) survives the conversion for the languages HEY highlights — Ruby, Python, JavaScript, TypeScript, Go, Rust, Java, C#, C++, PHP, Swift, HTML and CSS; any other is dropped.

Email - The Screener

hey screener list --json                      # Who is waiting to be screened
hey screener list --count                     # Just the number waiting (cheap)
hey screener approve 91                       # Let a sender through, into the Imbox
hey screener approve 91 --box "The Feed"      # Let them through, into another box
hey screener approve 91 --seen                # Deliver what they sent, marked read (see below)
hey screener deny 91 92                       # Turn several senders away
hey screener deny 91 --spam                   # Turn away as spam
hey screener history --json                   # Who has already been decided
hey screener clear                            # Trash everything waiting, deciding no one

The Screener is where first-time senders wait. hey screener list returns clearance IDs — not contact IDs and not posting IDs — with the sender, what they sent, and a topic_id for reading the thread before deciding. --count is a far cheaper request than the queue and prints a bare number.

Approving delivers everything that sender has waiting; denying hides it. Either is reversible with the opposite command. --box and --seen apply to one sender at a time; several IDs go through HEY's bulk endpoint, which takes neither. --seen reliably marks the mail read only when the sender has a single waiting thread; with several, HEY files them after answering and they can arrive unread. --spam marks what they sent as spam, and with a single ID also trains HEY's filter, which is harder to undo than a plain deny. hey screener clear moves everything waiting to Trash (a shared thread loses your access instead) without approving or denying anyone; those senders are screened again on their next email. It is queued, so list can lag briefly. Confirm with the user before running it.

Email - Bulk reply

hey bulk-reply preview 12345 67890 --json     # Read-only: threads and exact recipients
hey bulk-reply send 12345 67890 -m "Thanks for the update — noted."
hey bulk-reply undo 98765                     # Recall a delayed bulk reply

Takes box item IDs, which must be positive and unique. Always run preview first — it resolves each posting to the entry a reply would answer and shows the exact To/CC/BCC, so the blast radius is visible before anything sends. send resolves the selection again and skips threads with no replyable entry, then returns the reply count, delivery ID and delayed state, plus the undo URL and command when HEY delayed it (Undo Send on). undo works only within HEY's 15-second window. IDs that are not your box items are skipped: preview reports them in meta.skipped_count, and send with none left is a usage error.

Email - Seen/Unseen

hey seen 12345                                # Mark a thread as seen
hey seen 12345 67890                          # Mark multiple threads as seen
hey unseen 12345                              # Mark a thread as unseen
hey unseen 12345 67890                        # Mark multiple threads as unseen

Takes box item IDs (the id field from hey box view output).

Email - Moving Threads

hey move 12345 --to feed                      # Move one thread
hey move 12345 67890 --to "paper trail"       # Move multiple threads
hey move 12345 67890 --to imbox               # Remove Reply Later from threads

Takes box item IDs (the id field from hey box view --json). --to accepts a box name, kind, or ID. Supported destinations are Imbox, The Feed, Set Aside, Reply Later, and Paper Trail. Moving to any of them but Imbox marks the threads seen, and a thread that cannot be replied to is silently not moved to Reply Later. Reply Later is a box, not an independent flag: moving a Reply Later thread to Imbox removes Reply Later, preserves its seen state, and leaves a seen thread in Previously Seen. It does not return the thread to the box it occupied before Reply Later. Bubble Up goes through hey bubble instead. A bundle row is refused — moving it would unbundle that sender's mail; use hey contact bundle|unbundle <contact_id>.