Every HEY tool your AI assistant can use

What each tool takes, gives back, and what it can change.


This is the reference for HEY’s MCP server at https://mcp.hey.com/mcp, version 0.2.9. To connect an assistant, see Use HEY with your AI assistants.

The server offers 45 tools. Two of them, send_draft and screen_in_sender, act only after the person confirms, so they’re listed only to apps that can stop and ask (MCP form elicitation). Every other app sees 43 tools.

Each tool can only reach what the signed-in person can see in the HEY accounts they chose when they connected, and runs only when the assistant calls it. A tool needs the permission named under it: read for reads, write for changes, and send (off unless the person turns it on) for sending. A call the connection’s permissions don’t cover is refused before anything reaches HEY.

Read (22) tools change nothing in HEY. Write (20) tools change the person’s own mail organization, drafts, Screener or to-dos, and reach no one else. Sensitive write (3): send_draft delivers email to other people and can’t be recalled; screen_in_sender lets a new sender’s mail into the Imbox and within the assistant’s reach; delete_todo can’t be undone.

The hints are the MCP tool annotations each tool declares. destructiveHint is true for every write that changes or removes something, even when it can be undone in HEY; only writes that add something new (a draft, a to-do) are false. openWorldHint is true only for send_draft, the one tool that reaches people outside the account.

ToolClassRead onlyDestructiveIdempotentOpen world
get_meReadyesnoyesno
get_hey_guideReadyesnoyesno
get_by_urlReadyesnoyesno
get_imboxReadyesnoyesno
get_feedReadyesnoyesno
get_paper_trailReadyesnoyesno
get_reply_laterReadyesnoyesno
get_set_asideReadyesnoyesno
get_bubble_upReadyesnoyesno
search_mailReadyesnoyesno
get_threadReadyesnoyesno
get_messageReadyesnoyesno
list_draftsReadyesnoyesno
get_draftReadyesnoyesno
list_labelsReadyesnoyesno
get_screenerReadyesnoyesno
list_contactsReadyesnoyesno
get_contactReadyesnoyesno
list_calendarsReadyesnoyesno
get_calendar_itemsReadyesnoyesno
get_dayReadyesnoyesno
get_weekReadyesnoyesno
create_draftWritenononono
reply_draftWritenononono
update_draftWritenoyesnono
delete_draftWritenoyesyesno
send_draftSensitive writenoyesnoyes
move_to_imboxWritenoyesnono
move_to_feedWritenoyesnono
move_to_paper_trailWritenoyesnono
move_to_reply_laterWritenoyesnono
move_to_set_asideWritenoyesnono
mark_seenWritenoyesnono
mark_unseenWritenoyesnono
schedule_bubble_upWritenoyesnono
cancel_bubble_upWritenoyesyesno
add_labelWritenoyesnono
remove_labelWritenoyesyesno
screen_in_senderSensitive writenoyesyesno
screen_out_senderWritenoyesyesno
create_todoWritenononono
update_todoWritenoyesyesno
complete_todoWritenoyesyesno
uncomplete_todoWritenoyesyesno
delete_todoSensitive writenoyesyesno

The server declares no output schema. Every tool returns one JSON object, as both the result’s text and its structuredContent. Optional fields without a value are left out, and empty lists come back as []. A tool that asks the person to confirm (send_draft, screen_in_sender, and delete_todo where the app can ask) first returns that question, and the result below once they answer. A failure comes back as a tool error (isError: true) with a plain-language message, and nothing is changed unless the message says otherwise.

  • Paging. A list with more to show carries next_page; pass it back as page for the next page. A long message or draft body comes in parts: pass next_offset back as offset. A calendar day or week cut to fit continues from the offset in truncation.continue.
  • Size. A result is capped at 100 KB. A list page too large for one result holds fewer whole items and says so in truncation; its next_page starts at the first item it left out. A day or week too large for one result is cut the same way, and truncation.continue names the offset to call get_day or get_week again with.
  • Sender-written text. Every object with text a sender chose (a subject, a preview, a body, a display name or address, an event title) lists those fields in an _untrusted array, by path, such as "from.name" or "to[].address", so the assistant can tell a sender’s words from the person’s.
  • Withheld content. From a sender the person hasn’t screened in, or in a thread in spam, a read returns who sent it and when, never what they wrote. It says what it left out in withheld: { reason, fields, note }, where reason is unscreened_sender, spam, screening_unknown or thread_status_unknown.
  • Attachments. No tool returns an attachment’s content.

Shapes several tools share:

  • Person: { name, address, contact_id }
  • Thread in a box: { posting_id, topic_id, kind, subject, from, sender_display_name, to, summary, created_at, active_at, observed_at, seen, muted, includes_attachments, includes_calendar_invites, bubbled_up, bubble_up_at, visible_entry_count, note, app_url, screened_in: true, _untrusted }. from and to are people; summary is HEY’s short preview, not the body; note is the person’s own note on the thread. A kind: "bundle" item groups one sender’s threads, has no topic_id, and carries a bundle note.
  • Thread: { topic_id, subject, status, started_by, participants, created_at, active_at, app_url, is_forged_sender, sender_warning, screened_in, messages: [{ message_id, kind, from, sender_display_name, subject, summary, created_at, app_url, _untrusted }], withheld, _untrusted }. Messages are previews; sender_warning is HEY’s own warning when it couldn’t verify the sender.
  • Calendar item: { id, type, title, starts_at, ends_at, starts_at_time_zone, all_day, recurring, completed_at, location, description, notes, summary, content, label, category, attendances_summary, attendance_status, occurrence_id, url, calendar_id, calendar, organizer: { name, address }, join_link, message_id, _untrusted }. type is whatever HEY keeps on the calendar: events, to-dos, habits, journal entries, time tracking and the like. A journal entry’s text comes as a shortened content.
  • Draft saved: { draft_id, from, to, cc, bcc, sent: false, note, app_url, _untrusted }. Recipients are addresses; app_url opens the draft in HEY; note says how the person sends it.

get_me

Get my account. Returns the signed-in HEY user: a stable id, name and time zone, the HEY accounts they belong to, and the addresses they can send from.

Inputs
None
Returns
{ id, name, time_zone, address, accounts: [{ id, name, purpose, status }], senders: [{ sender_id, name, address, account_id, default }] }. address is the person’s primary address; senders are the From addresses the draft tools accept.
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Account profile, Email addresses

get_hey_guide

Get the guide. Returns reference notes on how HEY organizes mail (boxes, The Screener, threads and messages) and which tool works with each part.

Inputs
None
Returns
{ guide }: reference text the server writes about how HEY organizes mail and which tool reads or changes each part. It contains no account data.
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
None

get_by_url

Read a link. Reads what an app.hey.com link points at: a thread, a message, a draft, a contact, a box, The Screener, or a calendar day or week. Returns the same result as the matching tool, and names it in resolved. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
urlstringyesAn app.hey.com URL, such as https://app.hey.com/topics/123.
Returns
The same result as the tool the link resolves to (get_thread, get_message, get_draft, get_contact, a box read, get_screener, get_day or get_week), plus resolved: { tool, arguments } naming it. Only app.hey.com links of those shapes are read; any other link is refused. What it touches is what the resolved tool touches.
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Mail subjects and previews, Mail bodies, Email addresses, Contacts, Drafts, The Screener, Calendar events, To-dos, Journal, Habits, Time tracking

get_imbox

Read the Imbox. Reads the Imbox: mail from people and senders the account screened in. Lists threads in HEY’s order: those not yet seen first, then the rest, each part by observed_at, newest first. Each comes with sender, subject, HEY’s short preview, and the topic_id get_thread reads. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
Returns
{ box: "imbox", threads: [Thread in a box], next_page }
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Mail subjects and previews, Email addresses

get_feed

Read The Feed. Reads The Feed: newsletters and other mail the account reads as a stream. Lists threads newest first, by active_at. Each comes with sender, subject, HEY’s short preview, and the topic_id get_thread reads. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
Returns
{ box: "feed", threads: [Thread in a box], next_page }
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Mail subjects and previews, Email addresses

get_paper_trail

Read the Paper Trail. Reads the Paper Trail: receipts, notifications and other mail kept for the record. Lists threads newest first, by active_at. Each comes with sender, subject, HEY’s short preview, and the topic_id get_thread reads. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
Returns
{ box: "paper_trail", threads: [Thread in a box], next_page }
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Mail subjects and previews, Email addresses

get_reply_later

Read Reply Later. Reads Reply Later: threads the account saved to answer later. Lists threads in HEY’s order: those not yet seen first, then the rest, each part by observed_at, newest first. Each comes with sender, subject, HEY’s short preview, and the topic_id get_thread reads. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
Returns
{ box: "reply_later", threads: [Thread in a box], next_page }
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Mail subjects and previews, Email addresses

get_set_aside

Read Set Aside. Reads Set Aside: threads the account kept handy for reference. Lists threads in HEY’s order: those not yet seen first, then the rest, each part by observed_at, newest first. Each comes with sender, subject, HEY’s short preview, and the topic_id get_thread reads. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
Returns
{ box: "set_aside", threads: [Thread in a box], next_page }
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Mail subjects and previews, Email addresses

get_bubble_up

Read Bubble Up. Reads Bubble Up: threads scheduled to return to the top of the Imbox, with when each one returns. Lists threads in the order they return. Each comes with sender, subject, HEY’s short preview, and the topic_id get_thread reads. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
Returns
{ box: "bubble_up", threads: [Thread in a box], next_page }. Each thread also carries bubble_up_at.
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Mail subjects and previews, Email addresses

search_mail

Search mail. Searches the account’s mail by words, sender, recipient or subject, as HEY’s search page does. Returns matching threads with their matching messages. A thread whose sender isn’t screened in, or that is in spam, comes with its senders and dates only, and withheld says what was left out and why. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
exact_phrasestringnoOnly mail containing this exact phrase.
fromstringnoOnly mail from this name or address.
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
querystringnoWords to search for.
subjectstringnoOnly mail whose subject has these words.
tostringnoOnly mail to this name or address.
withoutstringnoLeave out mail containing any of these words.
Returns
{ threads: [Thread], next_page }. Each thread also carries posting_id where it is in one of the person’s boxes, and its messages are the matching messages, as previews. A thread from a sender who isn’t screened in, or in spam, is withheld. Needs at least one search argument besides page.
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Mail subjects and previews, Email addresses

get_thread

Read a thread. Reads one email thread: its subject, participants and messages in order, each with sender, time and a short preview. Use get_message with a message_id for a full message. A thread whose sender isn’t screened in, or that is in spam, comes with its senders and dates only, and withheld says what was left out and why. When HEY couldn’t verify the sender, sender_warning carries HEY’s own warning. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
topic_idintegeryesThe thread’s topic_id, from a box, search or contact result.
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
Returns
Thread, with up to a page of its messages as previews, and next_page for the rest. Full bodies come from get_message.
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Mail subjects and previews, Email addresses

get_message

Read a message. Reads one email message in full: sender, recipients, subject and the body as text inside an <email-content> block. Content HEY hides from view, such as hidden text and images, is left out. A long body comes a page at a time: when next_offset is present, call again with it as offset for the rest. A message whose sender isn’t screened in, or whose thread is in spam, comes with its sender and date only, and withheld says what was left out and why. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
message_idintegeryesThe message_id, from get_thread, search_mail or get_screener.
offsetintegernoCharacters into the body to start from: the next_offset of the previous page. Omit it for the start.
Returns
{ message_id, topic_id, subject, from, sender_display_name, to, cc, bcc, created_at, scheduled_delivery_at, app_url, box, screened_in, thread_status, body, body_length, offset, next_offset, hidden_content_omitted, body_unavailable, _untrusted }. from and each recipient are people. body is the message rendered to plain text inside an <email-content> block, a page at a time: call again with next_offset as offset for the rest. Text HEY hides from view is left out and counted in hidden_content_omitted. Attachments are never returned, only mentioned where the body names them. A message from a sender who isn’t screened in, or in spam, keeps only its sender and dates (withheld).
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Mail bodies, Mail subjects and previews, Email addresses

list_drafts

List drafts. Lists the account’s saved drafts, newest first, with subject, recipients and a short preview. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
Returns
{ drafts: [{ draft_id, subject, summary, to, blank, updated_at, scheduled_delivery_at, app_url, _untrusted }], next_page }. summary is a short preview; to is a list of people; blank marks a draft with nothing in it yet.
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Drafts, Email addresses

get_draft

Read a draft. Reads a saved draft as HEY will send it: the address it sends from, the To, Cc and Bcc lines, the subject, and the body as text, with its attachments, links and images named and anything the text can’t show listed in not_shown. A long body comes in pages, as get_message’s does. body_editable is true when update_draft can replace the body as text without losing formatting, links or attachments. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
draft_idintegeryesThe draft_id, from list_drafts, create_draft or reply_draft.
offsetintegernoCharacters into the body to start from: the next_offset of the previous page. Omit it for the start.
Returns
{ draft_id, from, to, cc, bcc, subject, attachments, links, images, not_shown, scheduled_delivery_at, app_url, sent: false, body, body_length, offset, next_offset, body_editable, body_unavailable, _untrusted }. from is the sending address; recipients are people; attachments, links and images name what the body carries (never attachment content). body is paged as in get_message; body_editable is true when update_draft can replace it as text without losing anything.
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Drafts, Email addresses

create_draft

Write a draft. Saves a new email as a draft in HEY’s Drafts, addressed and ready to send. It isn’t sent. The person sees or revises it as they like and sends it with one press of their own; the result’s note says how. The body is plain text.

Inputs
InputTypeRequiredDescription
bodystringyesThe message, as plain text. Blank lines separate paragraphs.
subjectstringyesThe subject line.
bccarray of stringsnoEmail addresses on the Bcc line.
ccarray of stringsnoEmail addresses on the Cc line.
fromstringnoThe address to send from, one of get_me’s senders. Omitted, the account’s default sender.
toarray of stringsnoEmail addresses on the To line.
Returns
Draft saved. Nothing is sent.
Class
Write
Hints
readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false
Permission
write
Data
Drafts, Mail bodies, Email addresses

reply_draft

Write a reply. Saves a reply to a message as a draft on its thread. It isn’t sent. Without to, cc or bcc it goes to whoever HEY would reply to; HEY quotes the original when it’s sent. The body is plain text. Review and sending work as for create_draft.

Inputs
InputTypeRequiredDescription
bodystringyesThe reply, as plain text, without the quoted original.
message_idintegeryesThe message_id being answered, from get_thread or get_message.
bccarray of stringsnoEmail addresses on the Bcc line.
ccarray of stringsnoEmail addresses on the Cc line.
fromstringnoThe address to send from, one of get_me’s senders. Omitted, the address HEY picks for the reply, as it does in the app.
toarray of stringsnoEmail addresses on the To line.
Returns
Draft saved, plus subject (HEY’s reply subject) and in_reply_to. Without to, cc or bcc, the recipients are the ones HEY would reply to. Nothing is sent.
Class
Write
Hints
readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false
Permission
write
Data
Drafts, Mail bodies, Email addresses

update_draft

Edit a draft. Changes a saved draft’s subject, body, recipients or sending address, keeping what isn’t given, as the person asks while reviewing it. A given body replaces the whole body. It isn’t sent. A draft scheduled to send is changed in HEY instead.

Inputs
InputTypeRequiredDescription
draft_idintegeryesThe draft_id, from list_drafts, create_draft or reply_draft.
bccarray of stringsnoEmail addresses for the Bcc line, replacing what’s there.
bodystringnoThe new body, as plain text. It replaces the whole body.
ccarray of stringsnoEmail addresses for the Cc line, replacing what’s there.
fromstringnoThe address to send from, one of get_me’s senders. Omitted, the draft keeps the address it sends from.
subjectstringnoThe new subject line.
toarray of stringsnoEmail addresses for the To line, replacing what’s there.
Returns
Draft saved, plus subject. Fields not given keep their saved values. A draft scheduled to send is refused. Nothing is sent.
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Permission
write
Data
Drafts, Mail bodies, Email addresses

delete_draft

Discard a draft. Moves a saved draft to HEY’s Trash, where it can be restored for 30 days.

Inputs
InputTypeRequiredDescription
draft_idintegeryesThe draft_id, from list_drafts, create_draft or reply_draft.
Returns
{ deleted: true, draft_id, note }. The draft is in HEY’s Trash for 30 days.
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false
Permission
write
Data
Drafts

send_draft

Send a draft. Sends a saved draft through HEY, called when the person asks to send it. The person confirms it here, in their assistant: they see who it goes to, from which address, the subject, every attachment, link and image, and the body, with a long body shown in part and anything the text can’t show named, so the draft needn’t be shown or asked about again first. Where the assistant can’t ask, it returns the draft’s link to send from HEY instead.

Listed only to apps that can ask the person to confirm (MCP form elicitation). Other apps don’t see this tool.

Inputs
InputTypeRequiredDescription
draft_idintegeryesThe draft_id, from list_drafts, create_draft or reply_draft.
Returns
Asks the person to confirm first, showing the sending address, every recipient, the subject, the body and what the text can’t show. Confirmed: { sent: true, draft_id, from, to, cc, bcc, subject, note }, where recipients are addresses. Declined: { sent: false, draft_id, note, app_url }. A draft that’s scheduled, or that sends from an address the account no longer lists, isn’t sent: { sent: false, draft_id, note, app_url }. The server never retries a send.
Class
Sensitive write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true
Permission
send, read
Data
Drafts, Mail bodies, Email addresses

move_to_imbox

Move to the Imbox. Moves threads to the Imbox, out of the box they’re in.

Inputs
InputTypeRequiredDescription
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
Returns
{ moved, box: "imbox", posting_ids }, where moved counts the threads
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels)

move_to_feed

Move to The Feed. Moves threads to The Feed, out of the box they’re in.

Inputs
InputTypeRequiredDescription
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
Returns
{ moved, box: "feedbox", posting_ids }, where moved counts the threads
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels)

move_to_paper_trail

Move to the Paper Trail. Moves threads to the Paper Trail, out of the box they’re in.

Inputs
InputTypeRequiredDescription
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
Returns
{ moved, box: "trailbox", posting_ids }, where moved counts the threads
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels)

move_to_reply_later

Move to Reply Later. Moves threads to Reply Later, out of the box they’re in.

Inputs
InputTypeRequiredDescription
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
Returns
{ moved, box: "laterbox", posting_ids }, where moved counts the threads
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels)

move_to_set_aside

Move to Set Aside. Moves threads to Set Aside, out of the box they’re in.

Inputs
InputTypeRequiredDescription
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
Returns
{ moved, box: "asidebox", posting_ids }, where moved counts the threads
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels)

mark_seen

Mark as seen. Marks threads as seen, as opening them in HEY does.

Inputs
InputTypeRequiredDescription
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
Returns
{ seen, posting_ids }, where seen counts the threads marked
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels)

mark_unseen

Mark as unseen. Marks threads as unseen, so they show as new in their box.

Inputs
InputTypeRequiredDescription
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
Returns
{ unseen, posting_ids }, where unseen counts the threads marked
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels)

schedule_bubble_up

Bubble Up. Schedules threads to return to the top of the Imbox later: this evening (today), tomorrow morning, the weekend, next week, a surprise day, or the morning of a date (custom).

Inputs
InputTypeRequiredDescription
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
whenstringyesWhen they come back. custom takes date. One of today, tomorrow, weekend, next_week, surprise_me, custom.
datestringnoFor custom, the date to come back on, as YYYY-MM-DD.
Returns
{ scheduled, when, date, posting_ids }, where scheduled counts the threads and date is present for custom
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels)

cancel_bubble_up

Pop. Pops threads: takes them out of Bubble Up, so they don’t return to the top of the Imbox, and leaves them where they are.

Inputs
InputTypeRequiredDescription
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
Returns
{ cancelled, posting_ids }
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels)

list_labels

List labels. Lists the account’s labels, with the label_id add_label and remove_label take.

Inputs
None
Returns
{ labels: [{ label_id, name }] }
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Labels

add_label

Add a label. Adds one of the account’s labels, from list_labels, to threads; a thread keeps its box and its other labels.

Inputs
InputTypeRequiredDescription
label_idintegeryesThe label_id, from list_labels.
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
Returns
{ labeled, label_id, posting_ids }
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels), Labels

remove_label

Remove a label. Takes one label off threads, leaving their other labels.

Inputs
InputTypeRequiredDescription
label_idintegeryesThe label_id, from list_labels.
posting_idsarray of integersyesThe posting_id of each thread, from a box read or search_mail. Up to 100.
Returns
{ unlabeled, label_id, posting_ids }
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false
Permission
write
Data
Mail organization (boxes, seen, Bubble Up, labels), Labels

get_screener

Read The Screener. Lists first-time senders waiting in The Screener: each sender’s name and address, when their newest message arrived, and its message_id. Nothing they wrote comes back until the person screens them in, and withheld says what was left out. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
Returns
{ senders: [{ clearance_id, status, from, message_id, received_at, screened_in: false, withheld, _untrusted }], pending_count, next_page }. Only who is waiting and when: never the subject, preview or body of what they sent.
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
The Screener, Email addresses

screen_in_sender

Screen In a sender. Screens in a sender waiting in The Screener, after the person confirms it: their mail then arrives in the Imbox, and what they wrote becomes readable here. Where the assistant can’t ask, it returns The Screener’s link instead.

Listed only to apps that can ask the person to confirm (MCP form elicitation). Other apps don’t see this tool.

Inputs
InputTypeRequiredDescription
clearance_idintegeryesThe sender’s clearance_id, from get_screener.
Returns
Asks the person to confirm first, showing the sender’s name and address. Confirmed: { screened_in: true, clearance_id, address }. Declined: { screened_in: false, clearance_id, note }. A sender further down The Screener than the tool looks returns screened_in: false and a link to The Screener.
Class
Sensitive write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false
Permission
write
Data
The Screener, Email addresses

screen_out_sender

Screen Out a sender. Screens out a sender waiting in The Screener: their mail stops arriving in any box, now and later. The person can screen them back in from HEY’s Screened Out list.

Inputs
InputTypeRequiredDescription
clearance_idintegeryesThe sender’s clearance_id, from get_screener.
Returns
{ screened_out: true, clearance_id }
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false
Permission
write
Data
The Screener

list_contacts

List contacts. Lists the account’s contacts, or finds them by name or address, with the contact_id get_contact reads. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
querystringnoA name or address to look for.
Returns
{ contacts: [{ contact_id, name, address, kind, name_tag, _untrusted }], next_page }
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Contacts, Email addresses

get_contact

Read a contact. Reads one contact: name, addresses, whether they’re screened in, and a page of the threads they’re on. Fields a sender wrote are listed in each item’s _untrusted array.

Inputs
InputTypeRequiredDescription
contact_idintegeryesThe contact_id, from list_contacts or a sender in any result.
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
Returns
{ contact_id, name, address, kind, name_tag, screener_status, screened_in, aliases, app_url, threads: [Thread in a box], next_page, _untrusted }. aliases are the contact’s other names and addresses; threads is a page of the threads they’re on.
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Contacts, Email addresses, Mail subjects and previews

list_calendars

List calendars. Lists the account’s HEY calendars, with the calendar_id get_calendar_items reads.

Inputs
None
Returns
{ calendars: [{ calendar_id, name, kind, owned, personal, external, owner_email_address }], selected_calendar_ids }
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Calendar events, Email addresses

get_calendar_items

Read a calendar. Reads one calendar’s events, to-dos and other items between two dates. Event titles, descriptions and locations often come from other people’s invitations, and are listed in _untrusted.

Inputs
InputTypeRequiredDescription
calendar_idintegeryesThe calendar_id, from list_calendars.
ends_onstringnoThe last date to include, as YYYY-MM-DD.
pagestringnoThe next_page value from the previous page of this list. Omit it for the first page.
starts_onstringnoThe first date to include, as YYYY-MM-DD.
Returns
{ items: [Calendar item], next_page }
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Calendar events, To-dos, Journal, Habits, Time tracking

get_day

Read a day. Reads everything on the account’s calendars for one day: events, to-dos and other items. Event titles, descriptions and locations often come from other people’s invitations, and are listed in _untrusted.

Inputs
InputTypeRequiredDescription
datestringyesThe date, as YYYY-MM-DD.
offsetintegernoItems into the day to start from: the offset in truncation.continue when a result was cut. Omit it for the start.
Returns
{ items: [Calendar item], offset, starts_at, ends_at, kind }, across all of the person’s calendars
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Calendar events, To-dos, Journal, Habits, Time tracking

get_week

Read a week. Reads everything on the account’s calendars for the week containing a date: events, to-dos and other items. Event titles, descriptions and locations often come from other people’s invitations, and are listed in _untrusted.

Inputs
InputTypeRequiredDescription
datestringyesThe date, as YYYY-MM-DD.
offsetintegernoItems into the week to start from: the offset in truncation.continue when a result was cut. Omit it for the start.
Returns
{ items: [Calendar item], offset, starts_at, ends_at, kind }, across all of the person’s calendars
Class
Read
Hints
readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false
Permission
read
Data
Calendar events, To-dos, Journal, Habits, Time tracking

create_todo

Add a to-do. Adds a to-do to the account’s HEY calendar, on a date or today.

Inputs
InputTypeRequiredDescription
titlestringyesWhat the to-do says.
datestringnoThe day it’s on, as YYYY-MM-DD. Omitted, today.
Returns
{ created: true, todo }, where todo is the new to-do as a Calendar item when HEY returns it
Class
Write
Hints
readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false
Permission
write
Data
To-dos

update_todo

Edit a to-do. Changes a to-do’s title. The day it’s on is changed in HEY.

Inputs
InputTypeRequiredDescription
titlestringyesThe new title.
todo_idintegeryesThe to-do’s id, from get_day, get_week or get_calendar_items.
Returns
{ updated: true, todo_id }
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false
Permission
write
Data
To-dos

complete_todo

Complete a to-do. Marks a to-do done.

Inputs
InputTypeRequiredDescription
todo_idintegeryesThe to-do’s id, from get_day, get_week or get_calendar_items.
Returns
{ completed: true, todo_id }
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false
Permission
write
Data
To-dos

uncomplete_todo

Reopen a to-do. Marks a done to-do as not done.

Inputs
InputTypeRequiredDescription
todo_idintegeryesThe to-do’s id, from get_day, get_week or get_calendar_items.
Returns
{ reopened: true, todo_id }
Class
Write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false
Permission
write
Data
To-dos

delete_todo

Delete a to-do. Deletes a to-do for good: HEY keeps no trash for to-dos. Where the assistant can ask, the person confirms it first.

Inputs
InputTypeRequiredDescription
todo_idintegeryesThe to-do’s id, from get_day, get_week or get_calendar_items.
Returns
{ deleted: true, todo_id }. Where the app can ask, the person confirms first, and declining returns { deleted: false, note }.
Class
Sensitive write
Hints
readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false
Permission
write
Data
To-dos

Questions? Email support@hey.com.