search

Search Gmail with native query syntax (e.g. 'in:inbox from:foo@bar.com newer_than:7d'). Returns thread summaries; read-state/category predicates are re-verified against each hit's live labels. from, subject and date are the thread's FIRST message (its origin); snippet is Gmail's and comes from the LAST. lastMessageDate and lastMessageId name that last message, so 'did anything new arrive?' is a comparison of lastMessageId against the one you saw, not of messageCount against a remembered count — and get_thread with afterMessageId: <the id you saw> then returns only what is new. lastMessageFrom names who wrote that last message and lastMessageSent is true when it was this mailbox, so 'has the other side answered?' is lastMessageSent: false. unread is true when any message of the thread is unread, read off the live labels rather than the search index. attachments lists what is attached (filename, declared mimeType, size; at most 10, attachmentCount is the total), so 'is there a PDF to keep before archiving?' needs no get_thread — the mimeType is what the sender declared, so check the filename too when it says application/octet-stream. Each summary carries signals derived from the thread's first message headers/MIME — newsletter (List-Id/List-Unsubscribe/Precedence bulk, junk or list), automated (Auto-Submitted, auto-reply/suppress headers, no-reply-style senders), calendar (text/calendar or .ics part), replyToMismatch (a Reply-To on another domain than From — a subdomain of the same domain counts as the same), displayNameSpoof (the From display name shows an address or URL on another domain than the one the mail came from), lookalikeDomain (a From domain label mixing Latin with Cyrillic, Greek or Armenian letters); empty when nothing is declared. Paginated: when more results exist, the response carries a nextPageToken — pass it back via pageToken to fetch the next page. A page can come back with FEWER threads than maxResults and still have a nextPageToken: false positives from the index consume the scan window, and on a mailbox whose read state the index has fallen behind on, most candidates for an is:unread query can be already-read mail. A short page is therefore not evidence that the result set is exhausted — only an absent nextPageToken is. SPAM AND TRASH ARE EXCLUDED unless the query names them. Gmail leaves both out of any query that does not say in:spam / in:trash, so a plain from:someone returns nothing for a mail that is sitting in spam — measured against a live mailbox, not assumed. Nothing in the result marks the omission, so treat 'no hits' as 'none outside spam and trash'. When mail the user expects is missing, retry with in:spam before reporting that it does not exist: mail is often filed as spam because of something the user just did — a signup, a password reset, an order confirmation — which is precisely what a spam filter cannot know and the caller often can. USE WHEN: locating threads by sender, subject, date, label, or read state. DO NOT USE: to fetch a thread you already have the ID of (use get_thread). SIDE EFFECTS: none.