Organising

Mark email threads as read

Mark email threads as unread

Add or remove labels on email threads. Name each label by its id (USER_RECEIPTS) or by its name as getUserLabels lists it. The system labels STARRED, IMPORTANT, UNREAD, INBOX and ARCHIVE are accepted too, so archiving is adding ARCHIVE and removing INBOX. A label that does not exist is refused rather than created: call createLabel first.

The labels in this workspace, sorted by name. Each line gives the name, the id that modifyLabels, updateLabel and deleteLabel take, the colour (a hex value or a gradient token such as gradient:sunset) and how many conversations carry the label. An id comes from the name the label was created with and never changes, even after a rename. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

One label in detail: its name, id, colour, how many conversations carry it, and when it was created and last changed.

Create a new email label. A workspace holds at most 50 of them. The id comes from the name (Big Clients becomes USER_BIG_CLIENTS), so a name another label already has, or whose id another label holds, is refused. Leave backgroundColor out for a label with no colour. A label colour is a hex colour such as #3B82F6, or one of the gradient tokens gradient:sunset, gradient:ember, gradient:meadow, gradient:lagoon, gradient:aurora, gradient:berry, gradient:midnight. The app offers #EF4444, #F97316, #EA9602, #DCB30B, #79BB19, #2EB45C, #00AD9B, #09A9CA, #3B82F6, #6366F1, #8B5CF6, #D946EF, #EC4899, #64748B as its solid swatches, and any other hex is kept as it is. With aiInstructions and aiEnabled, AI applies the label to arriving mail that fits what you wrote, and testLabel tries it on recent mail first.

Rename or recolour a label, or change what AI does with it. Name it by its id or its current name, and give any of name, backgroundColor, aiInstructions and aiEnabled: a field left out stays as it is, and an empty backgroundColor clears the colour. The id never changes, so every conversation keeps the label through a rename. A label colour is a hex colour such as #3B82F6, or one of the gradient tokens gradient:sunset, gradient:ember, gradient:meadow, gradient:lagoon, gradient:aurora, gradient:berry, gradient:midnight. The app offers #EF4444, #F97316, #EA9602, #DCB30B, #79BB19, #2EB45C, #00AD9B, #09A9CA, #3B82F6, #6366F1, #8B5CF6, #D946EF, #EC4899, #64748B as its solid swatches, and any other hex is kept as it is.

Delete a label for good and take it off every conversation that carries it. The conversations stay where they are. There is no undo: creating the same name again gives the same id, but the conversations do not get the label back. Name the label by its id or its name, and check with the person you are working for first.

Move email threads to the Bin, as the delete button of the app does: each one leaves the inbox, spam, snoozed and archive at once, and a snoozed one no longer wakes. Nothing is deleted, and restoreThreads takes them back out.

Take email threads out of the Bin or Spam and put them back in the inbox, as Restore from Bin does. A thread that is already in the inbox stays there.

Delete email threads for good, every message and attachment in them, as Delete from Bin does in the app. This cannot be undone. To throw mail away without losing it, use trashThreads instead.

Hide email threads until a set time, as Snooze does: each leaves the inbox and comes back to it at wakeAt, an ISO 8601 instant in the future such as 2026-10-05T09:00:00Z. Threads wake at an hourly sweep, so up to an hour late. Snoozing a snoozed thread again replaces its wake time. getCurrentDate gives the time now.

Bring snoozed email threads back to the inbox now and cancel their wake time. A thread that is not snoozed is left as it is and reported.

Mute email threads, as Mute does: a thread in the inbox moves to the archive, and from then on new mail in it goes straight to the archive, unread, with no push, sound or desktop notice. It mutes the thread for everyone on the workspace, and mail addressed only to one person does not bring it back. unmuteThreads undoes it.

Take the mute off email threads, so the next message in each arrives in the inbox and alerts people again. The threads stay where they are: move one back to the inbox with modifyLabels if it should be there now. A thread that is not muted is left as it is.

The reminders set on mail you sent, newest first: waiting for a reply, answered, due (the time came with no reply and the thread is back in the inbox) or cancelled. status keeps one state and threadId the reminders of one thread.

Ask to be reminded about a thread if nobody replies by remindAt, an ISO 8601 time in the future, at most a year ahead. If a real reply arrives first the reminder closes by itself. Otherwise the thread returns to the top of the inbox, unread, with a push. Automatic replies, delivery reports and your own sending address do not count as a reply. A thread holds one waiting reminder per person, so setting another moves the time. To set one while sending, pass followUpAt to sendEmail or replyToEmail. getCurrentDate gives the time now.

Cancel a waiting reminder by its id from listFollowUps, so the thread stays where it is when the time comes. A reminder that already ended is reported as it is.

The senders whose mail always goes to one inbox tab. New mail is sorted into primary, promotions, updates, social or forums by plain rules, and a choice listed here wins over them.

Always sort mail from one sender into one inbox tab: primary, promotions, updates, social or forums. It also moves the inbox threads whose newest message is from them into that tab. Saving again replaces the choice.

Remove the tab choice of one sender, so new mail from them is sorted by the rules again. Threads already sorted stay where they are.

Try a label on recent mail: runs the AI over the newest inbox threads and says which ones the label would catch, without labelling anything. Pass aiInstructions to try wording that is not saved yet, or leave it out to try what the label holds. It spends one AI action, which the labelling of arriving mail never does.