Threads

Reads the local index. Passing query searches that same index.

Plain words must all appear, and each one matches loosely: case, accents and separators are ignored and part of a longer word counts, so min and ben jamin both find "Benjamin". A quoted phrase is matched as written apart from case and accents, so its separators have to line up: "ben jamin" does not find "Ben-Jamin", while "quarterly invoice" finds "Quarterly invoice". When nothing matches exactly, close spellings are returned instead, so benjimin finds "Benjamin": a plain word, or the value of from:, to:, cc:, subject:, body:, filename: or label:, may differ from the start of a word by one typo (a changed, missing, extra or swapped letter) when it has four to seven letters and by two when it has eight or more, while a quoted phrase, a word containing a digit, a shorter word and an excluded word still match exactly, and the pages that follow keep matching the same way. Filler words are dropped from a list of plain words when something else is left to search for, so mail server searches for server alone and emails from john searches for john. The filler is a, an, the, and, or, of, to, from, for, about, with, in, on, at, by, my, me, all, any, some, show, find, get, email, emails, mail, mails, message, messages, thread and threads, and it is kept when dropping it would leave nothing but a single letter.

Operators narrow the search: from:, to:, cc:, subject:, body:, label:, filename:, in: (inbox, sent, drafts, spam, trash, archive, snoozed, anywhere or a label name), is: (unread, read, starred, important, snoozed, muted, draft, sent, bounced for a delivery failure notice, unlabelled for a conversation that carries none of your labels), has: (attachment, pdf, image, video, audio, document, spreadsheet, presentation, userlabels, nouserlabels), after:YYYY/MM/DD, before:YYYY/MM/DD, newer_than:7d and older_than:1y (units h, d, w, m, y). Combine them with OR, AND, NOT, parentheses, braces for a set of alternatives ({stripe paddle}) and a leading - to exclude. Recipients are stored as one list without roles and never hold a Bcc, so cc: reads the same field as to: and bcc: matches nothing of its own. from:me is mail you sent, and to:me is mail carrying one of your own addresses, aliases included, among its recipients or as the address it was delivered to.

A value the search cannot use is ignored rather than narrowing, so a typo in a value widens the result instead of emptying it. Ignored: category:, larger:, smaller:, size:, messagesize:, list:, rfc822msgid:, received:, sent:, the category words (is:primary, is:personal, is:social, is:promotions, is:updates, is:forums, is:reservations, is:purchases), a has: word that names none of the kinds above, an importance: other than high or low, a date that cannot be read, and a duration whose unit is not h, d, w, m or y. An operator name it does not know, project: for instance, is searched as plain text instead.

Words and the from:, to:, cc:, subject: and body: operators read only the newest message on each thread: its sender, its recipients, its subject and the first 4,000 characters of its body. filename: and has: read every attachment on the whole conversation, and label:, in: and is: read the whole conversation. A plain word also matches the name of any attachment on the conversation, whichever message carried it. A message that arrived encrypted has no body text to match. folder still applies unless the query names one with in:, or with an is: that is a folder such as is:sent, and in:anywhere searches every folder, on its own as well as beside other terms. A drafts listing is the exception: GET /drafts and GET /threads?folder=draft stay in drafts whatever the query names.

Dates read the newest activity on the thread, in UTC. after: includes the day it names and before: excludes it. A date can be written YYYY/MM/DD, YYYY-MM-DD, YYYYMMDD, as a bare year, or as epoch seconds or milliseconds; A short date reads day first (16/09/2026), unless the second number cannot be a month (09/16/2026), and a number above 12 settles it either way. A day that does not exist is rejected and ignored.

Send semantic=true to match the plain words of query by meaning rather than by spelling. Describe the mail in a few words, such as flight to Berlin or invoices I still owe, in any language, and the threads closest in meaning come back best match first, together with every thread the words match as text, which ranks above a thread that only means the same. A thread is kept only when it is clearly closer to the words than the rest of the mailbox, so a description nothing fits returns only the text matches. Operators narrow the search exactly as above and folder and the other filters still apply, while sort does not. Meaning is read from the whole conversation, newest messages first and up to 12,000 characters, so an earlier message counts too. A conversation with an encrypted message is never read for meaning and is found by its text alone, new mail can be found by meaning about a minute after it arrives, and a workspace that turned search by meaning off in its settings (semanticSearch: false) gets a text search whatever semantic says. A query with no plain words, from:ada on its own for instance, is a text search whatever semantic says.

nextPageToken is opaque. Pass back what you were given, never construct one.

Requires the threads:read scope.

Every message in it, not only the most recent.

The messages are passed through as the mailbox stored them rather than projected onto a field list, and this document describes only encryption, which is the one field whose absence a caller cannot safely guess at. A message that arrived encrypted carries it and has an EMPTY BODY; read encryption.format before concluding a message was empty, and note that the two *-signed formats are ordinary readable mail.

Requires the threads:read scope.

Applies and removes labels, and sets read state, on one conversation. Label ids come from GET /labels; the system ids INBOX, ARCHIVE, STARRED, IMPORTANT, SPAM and UNREAD are taken in any case, so archiving is addLabelIds: ["ARCHIVE"] with removeLabelIds: ["INBOX"]. MUTE in addLabelIds mutes the thread as POST /threads/{id}/mute does, and the tab labels CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_SOCIAL and CATEGORY_FORUMS move a thread between inbox tabs. An id in addLabelIds that names no label is a 422 label_not_found, and nothing on the thread changes: create the label with POST /labels first. An unknown id in removeLabelIds is not an error, since the thread does not carry it. TRASH, SNOOZED and DRAFT are refused with label_not_directly_settable; use the trash and snooze endpoints.

Requires the threads:write scope.

Deletes every message in the thread, with its attachments, and cannot be undone, which is what Delete from Bin does in the app. It works on a thread in any folder, so move it to the Bin with POST /threads/{id}/trash when you only mean to throw it away.

Requires the threads:write scope.

Clears INBOX, SPAM, SNOOZED and ARCHIVE together, which is what the app does. Adding the TRASH label by hand through PATCH is refused, because doing only half of it leaves the thread listed in the Bin AND its old folder.

Requires the threads:write scope.

Hides it and schedules its return. Both halves happen together: the label hides it, a stored wake time brings it back, and a thread snoozed by label alone never returns.

Requires the threads:write scope.

Brings it back now and cancels the scheduled return.

Requires the threads:write scope.

content is base64, and an empty string where the stored bytes could not be found.

This is the DISPLAY list. Of the parts named by a message's encryption.parts, the ciphertext part IS listed and downloads like any other file (it is the message, and downloading it is the only way an API client reads this mail). The PGP/MIME version part and any detached signature are held out deliberately, because they rendered as junk attachments and there is nothing a caller can do with them. Both keep their ids in encryption.parts, which correlates the two views, and this endpoint does not return them.

Requires the threads:read scope.

What the sidebar of the app shows: how many conversations each folder holds and how many of them are unread, how many drafts are waiting, how many conversations each of your labels has in each folder, how many inbox conversations sit in each tab, and how many inbox conversations arrived at each address. unread is a pseudo-folder whose count is the unread conversations in the inbox, and draft counts drafts, which are never unread. A key or an app limited to particular addresses counts only the mail that arrived at them and the drafts written from them, and address narrows the counts to one address, never wider than that.

Requires the threads:read scope.

The short AI summary the reading pane shows above a thread. It is written the first time it is asked for and then kept, and the first request after a newer message arrives writes it again, so reading it is cheap. state is ready with the summary, pending while the first one is being written (ask again in a few seconds), or none when there is nothing to summarise, such as a thread holding a message that arrived encrypted. While a newer summary is being written, the one before it comes back as ready. Summaries spend no AI actions.

Requires the threads:read scope.

Puts a thread back in the inbox, out of the Bin and out of Spam, which is what Restore from Bin and Move to inbox do in the app. It is the undo of POST /threads/{id}/trash, and calling it again changes nothing.

Requires the threads:write scope.

Up to 3 short replies to the latest message of the thread, the ones the reading pane offers under it. Each has a label, a few words that say what it answers, and a body, the reply itself, ready to send with POST /emails or to keep with POST /drafts. They are written in the language of that message and the voice of the mail this workspace sends, from the conversation, what was written to this correspondent before, what is known about their organisation and, when the message asks for a time, the free and busy times of the calendar.

Suggestions are written once for each new message and kept, so asking again is free until another message arrives. state is ready with the suggestions, pending while they are being written (ask again in a few seconds), or none when the message needs no reply: your own reply came last, or it is a newsletter, an automated notice, mail from a no-reply address, spam or an encrypted message, and every thread is none in a workspace that turned replySuggestions off in its settings. messageId names the message they answer. Writing suggestions spends no AI action, and a workspace has suggestions written for at most 500 new messages a day.

Requires the threads:read scope.

Mutes a conversation, as Mute does in the app. 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. A webhook for that mail carries muted: true. Thread state belongs to the whole workspace, so the thread is muted for everyone on it, and mail addressed only to you does not bring it back. Calling it again changes nothing. PATCH /threads/{id} with MUTE in addLabelIds does the same.

Requires the threads:write scope.

Takes the mute off, so the next message in the thread arrives in the inbox and alerts people again. The thread stays where it is: move it back with PATCH /threads/{id} and INBOX if you want it in the inbox now. A thread that is not muted is left as it is.

Requires the threads:write scope.

The reminders you set on mail you sent, newest first: the ones still waiting for a reply and the ones that ended. A reminder is waiting until somebody replies (answered), its time comes with no reply (due, and the thread is back at the top of the inbox, unread) or it is cancelled. An API key lists the reminders of the workspace owner, and an app those of the person who connected it. A key or an app limited to particular addresses lists only reminders on threads delivered to them.

Requires the threads:read scope.

Asks to be reminded about a thread if nobody replies by remindAt. If a real reply arrives first, the reminder closes by itself. Otherwise, when the time comes, the thread returns to the top of the inbox, unread, with the built-in FOLLOW_UP label and a push to your phones. 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 as you send, pass followUpAt to POST /emails instead.

Requires the threads:write scope.

Cancels a waiting reminder, so the thread stays where it is when the time comes. A reminder that already ended is returned as it is. Only your own reminders can be cancelled.

Requires the threads:write scope.

The senders whose mail always goes to one inbox tab, by address. New mail is sorted into Primary, Promotions, Updates, Social or Forums by plain rules, and a choice saved here wins over them. GET /threads takes category to read one tab.

Requires the threads:read scope.

Saves the tab for one sender and moves the inbox threads whose newest message is from them, up to the newest 1,000, into it. Mail from them is sorted there from now on, whatever the rules would say. Saving again replaces the choice. A workspace holds at most 2,000 choices, and they apply to every address in it, so a key or an app limited to particular addresses or domains can read them but not change them.

Requires the threads:write scope.

Removes the choice, so new mail from the sender is sorted by the rules again. Threads already sorted stay where they are.

Requires the threads:write scope.

Every message on the thread, oldest first, each as a MailboxMessage with its sender, recipients, date, Message-ID, text and HTML body, attachments and headers. Unsent draft replies are in the list with draft: true. The fields here are a contract: they are added to, never renamed or taken away, whatever the mailbox stores underneath. GET /threads/{id} still returns each message the way the mailbox stored it.

Requires the threads:read scope.

One message, in the shape GET /threads/{id}/messages lists. The thread is checked first and then the message, so a message that is not on that thread is a 404 even when it exists elsewhere in the mailbox. The fields here are a contract: they are added to, never renamed or taken away, whatever the mailbox stores underneath. GET /threads/{id} still returns each message the way the mailbox stored it.

Requires the threads:read scope.