Schedule an email thread to bubble up (reappear) at a specific time. Returns {success, error?}. Reversible via hey_pop_bubble. Requires the thread's topic_id (use topic_id from any list operation); posting IDs are not accepted and will 404.

Schedule an email thread to bubble up ONLY if there's no reply by a deadline date. Returns {success, error?}. The thread only reappears if no reply arrives. Reversible via hey_pop_bubble. Requires the thread's topic_id (use topic_id from any list operation); posting IDs are not accepted.

Get local cache statistics: message counts, cache age, and storage estimate. Read-only with no side effects. Pass folder to scope message/unread counts to one cached view. Use before deciding whether to pass force_refresh on other list tools.

Add or remove an email thread from a collection. Returns {success, error?}. Reversible by calling again with the opposite action. Use hey_list_collections to discover collection IDs.

Permanently delete a draft by ID. This does not move it to Trash — it is gone immediately, same as the trash icon in Hey's Drafts list. Returns {success, draftId, error?}. Irreversible; there is no hey_restore_draft. Use hey_list_emails(folder='drafts') first if you don't already have the draftId from hey_save_draft or hey_edit_draft.

Download a single attachment from an email and save it to disk. First call hey_read_email to get the attachments[] array with IDs, filenames, and sizes, then call this tool with the attachment_id to save the file. Returns {local_path, filename, size, mime}.

Update an existing draft's recipients, subject, or body. Every field you pass replaces the draft's current value outright (no merging) — omit a field to leave it as Hey last saved it. Returns {success, draftId, error?}. Previous field values are not recoverable once overwritten, so re-fetch via hey_list_emails(folder='drafts') first if you need to preserve them. Use hey_save_draft to create a draft before calling this, and hey_delete_draft to remove one instead of blanking it out.

Forward an existing email to new recipients immediately. The original thread remains unchanged. Returns {success, error?}. Use instead of hey_send_email when sharing existing content; use hey_reply for responding within a thread.

Extract and parse a calendar invite (.ics) from an email. First call hey_read_email — if calendar_invites[] is present, call this tool to get full details: title, start, end, location, attendees, organizer, description, and raw_ics. To save the .ics file to disk, use hey_download_attachment instead.

Get a complete Imbox summary including screener count, bubbled up emails, and new emails. Use this for a comprehensive view of the inbox state.

Add or remove a label on an email thread. Returns {success, error?}. Reversible by calling again with the opposite action. Use hey_list_labels to discover available label IDs.

List emails in a specific collection. Returns cached results unless force_refresh=true.

List all collections in Hey.com. Returns array of {id, name}. Use the id with hey_collection or hey_list_collection_emails.

List emails in a Hey.com folder/view. Returns cached results unless force_refresh=true. Each email includes id, topicId, postingId, entryId, from, subject, date, and unread status. For folder=sent, from is always "Me" and the recipient (unverified against a live Sent page) is under to/toEmail instead.

List emails with a specific label. Returns cached results unless force_refresh=true.

List all labels/folders in Hey.com. Returns array of {id, name}. Use the id with hey_label or hey_list_label_emails.

List emails currently in the Reply Later stack. Returns cached results (same shape as hey_list_emails) unless force_refresh=true. Use hey_remove_reply_later with the returned postingId to remove an item.

List senders waiting in the Screener for approval. Returns cached results (same shape as hey_list_emails, plus clearanceId) unless force_refresh=true. Use hey_screen_by_id with the returned clearanceId to approve or reject.

List emails currently in the Set Aside stack. Returns cached results (same shape as hey_list_emails) unless force_refresh=true. Use hey_unset_aside with the returned postingId to remove an item.

Clear the orange 'New for you' tray dot — mirrors Hey's 'Mark all as seen' UI affordance. Returns {success, error?}. Pass a posting_id to clear just that one item (POST /postings/seen); omit posting_id to clear the entire Imbox tray in one call (POST /boxes/{imboxId}/observation). Reversible per-item via hey_mark_unseen. Use after triaging or skimming a batch to keep the tray tidy without re-marking threads unread.

Mark a thread as unseen/unread to reset its read status. Returns {success, error?}. Reading the email via hey_read_email implicitly marks it as seen again. To clear the orange 'New for you' tray dot without re-marking unseen, use hey_mark_seen.

Move an email thread between Hey.com views: imbox, feed, or paper_trail. Returns {success, error?}. Use paper_trail for receipts/automated mail, feed for newsletters, imbox to restore. Reversible by moving to a different destination. Does not affect trash, spam, or screener — use hey_set_status or hey_screen for those.

Pop (dismiss) a bubbled-up email thread so it sinks back into the Imbox. The thread is not deleted — it just stops being pinned at the top. Returns {success, error?}. Requires the thread's topic_id (use topic_id from any list operation); posting IDs are not accepted.

Read an email thread's full content. Returns all messages in the thread via entries[] array (each with entryId, from, to, cc, date, body). Also returns attachments[] metadata and calendar_invites[] when present — use hey_download_attachment to save files to disk, or hey_get_calendar_invite to parse .ics details. Use format='html' (default) for rich content with thread entries, or format='text' for decoded RFC822 plain text of the first message.

Set the read/unread status of an email entry. Returns {success, error?}. Reversible by calling again with the opposite status. Operates on individual entries (use entryId), not whole threads. For marking an entire thread as unseen, use hey_mark_unseen instead.

Remove an email from Reply Later, marking it "Done" and moving it back to the Imbox. Returns {success, error?}. Requires the posting_id from hey_list_reply_later. Reversible by calling hey_reply_later again with the thread's topic_id.

Reply to an email thread, preserving threading on both ends. Returns {success, error?}. By default the reply goes to the other thread participants (your own address is automatically excluded); pass to to redirect to specific recipients — e.g. chasing your own thread without looping back to yourself, or redirecting off a mailing-list address. Prefer this over hey_send_email when responding to an existing thread; use hey_send_email only for new conversations.

Move an email thread to Reply Later. Reversible via hey_remove_reply_later (requires postingId from hey_list_reply_later). Returns {success, error?}. Use for emails you intend to respond to but not right now — if no reply is planned, use hey_set_aside instead.

Save a new draft email without sending it. Creates an entry in Hey's Drafts folder; recipients, subject, and body are all optional so a partially-written draft can be saved. Returns {success, draftId?, error?}. Sending isn't available via MCP yet — finish and send the draft from the Hey web/app UI, or use hey_edit_draft to keep revising it. Use hey_send_email/hey_reply instead when you want to send immediately rather than draft first.

Approve or reject a sender by email address. Approve: routes the sender's current and future emails into the chosen destination (defaults to imbox). Reject (a.k.a. screen out): blocks the sender from sending you further emails — works for both pending screener entries AND already-approved senders (falls back to the contact-page 'Screened Out' affordance via /contacts/{id}/clearance). Reject does NOT flag emails as spam; existing emails are left untouched. Reversible from the Hey UI by visiting the contact page; not yet exposed via MCP. Returns {success, error?}. Use hey_list_screener to see pending senders, or hey_screen_by_id for clearance IDs.

Approve or reject a first-time sender from the Screener by clearance ID. Approve: allows future emails from this sender into the chosen destination (defaults to imbox). Reject: blocks future emails from this sender via the screener. Reversible from the Hey UI's contact page (not yet via MCP). Returns {success, error?}. Use hey_list_screener to get clearance IDs; for senders that have already left the screener, use hey_screen by email instead.

Search emails by query. Uses local FTS cache first, then network. Use force_refresh for real-time results.

Send a new email immediately (no draft stage). Returns {success, error?}. Use for standalone outbound messages; use hey_reply for thread responses, or hey_forward to share existing emails with new recipients.

Move an email thread to Set Aside for later. Reversible via hey_unset_aside (requires postingId from hey_list_set_aside). Returns {success, error?}. Use for emails you plan to revisit but don't need to reply to — for emails needing a reply, use hey_reply_later instead. Does not affect future emails from the sender.

Change an email thread's status. Returns {success, error?}. Trash and spam are reversible via restore and unspam actions respectively. DESTRUCTIVE: trash removes from Imbox, spam blocks the sender. Paper Trail bundles (postingId-only items with no thread) support action=trash only; spam/restore/unspam on a bundle return an explicit error pointing to the bundle's individual entries.

Mute or unmute a thread (called 'Ignore' in Hey.com's UI). Muting stops notifications for the thread but keeps it in its current view — the thread is not moved or deleted. Returns {success, error?}. Reversible by calling with the opposite action. To check if a thread is currently muted, use hey_read_email — the response includes a 'muted' field.

Remove an email from Set Aside, moving it back to the Imbox or its original location. Returns {success, error?}. Requires the posting_id from hey_list_set_aside. Reversible by calling hey_set_aside again with the thread's topic_id.