Conversaciones

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), 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.

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"]. 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, and how many inbox conversations arrived at each address. unread is a pseudo-folder whose count is the unread conversations in the inbox. A key or an app limited to particular addresses counts only the mail that arrived at 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 once and kept, and written again when a new message arrives, so reading it is cheap. state is ready with the summary, pending while 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. Writing a summary spends one of the workspace's 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.