Gmail API Search Queries
Comprehensive reference guide to Gmail search operators and syntax for filtering messages in automated workflows.
Overview
Gmail queries allow you to isolate exact messages based on sender, subject, date, read status, and attachment attributes. These query expressions are configured in the Search Query parameter of Fetch Mail (Gmail) and Fetch Single Mail (Gmail).
Common Gmail Query Operators
| Query | Function | Example |
|---|---|---|
is:unread | Matches only unread messages. | is:unread from:[email protected] |
is:read | Matches read messages. | is:read subject:statement |
in:inbox | Scopes search to the Inbox. | in:inbox is:unread |
in:sent | Scopes search to Sent mail. | in:sent to:[email protected] |
in:trash | Searches deleted items in Trash. | in:trash |
in:spam | Searches messages in Spam. | in:spam |
has:attachment | Matches messages containing files. | has:attachment filename:pdf |
larger:5m | Messages with total size over 5 megabytes. | larger:5m |
smaller:1m | Messages with total size under 1 megabyte. | smaller:1m |
Sender & Recipient Filters
| Operator | Syntax | Description |
|---|---|---|
from: | from:[email protected] | Matches emails from a specific sender address or domain. |
to: | to:[email protected] | Matches emails sent directly to the specified recipient. |
cc: | cc:[email protected] | Matches emails where the address is CC'd. |
bcc: | bcc:[email protected] | Matches emails where the address is BCC'd. |
Label & Category Filters
| Operator | Target | Description |
|---|---|---|
label: | label:important, label:finance | Scopes query to a specific system or user label. |
category:primary | Primary Inbox tab | Filters emails categorized as Primary by Gmail. |
category:social | Social tab | Notifications from social networks. |
category:promotions | Promotions tab | Marketing and commercial emails. |
category:updates | Updates tab | Receipts, statements, and bills. |
category:forums | Forums tab | Discussion boards and mailing lists. |
Date & Time Filters
| Operator | Format | Description |
|---|---|---|
newer_than: | newer_than:1d, newer_than:2h | Matches emails received within the last relative time window (d = days, h = hours, m = months). |
older_than: | older_than:7d | Matches emails older than the specified relative duration. |
after: | after:2025/01/01 | Absolute date lower bound (YYYY/MM/DD). |
before: | before:2025/12/31 | Absolute date upper bound (YYYY/MM/DD). |
Attachment Filters
| Operator | Syntax | Description |
|---|---|---|
has:attachment | has:attachment | Requires at least one attachment present. |
filename: | filename:pdf, filename:invoice.pdf | Matches specific file extensions or file names. |
Content & Keyword Matching
| Operator | Syntax | Description |
|---|---|---|
subject: | subject:"Verification Code" | Matches exact subject line text when quoted. |
| Exact phrase | "account created" | Matches the exact phrase anywhere in subject or body. |
| Negation | -from:spam.com | Excludes matching messages using the - prefix. |
Combining Operators
Multiple operators can be chained with spaces (equivalent to logical AND) or grouped with OR:
Compound AND
text
from:[email protected] is:unread newer_than:1hMatches unread messages from [email protected] received within the last hour.
Compound OR
text
from:([email protected] OR [email protected]) subject:OTPMatches messages from either sender containing "OTP" in the subject.
Automation Best Practices
- Always Use
newer_thanfor OTPs: Addnewer_than:1hornewer_than:1dto ensure past authentication emails are not returned. - Combine
is:unreadwith Read Flagging: Useis:unreadalongside the Remove UNREAD Label setting in the field configuration to guarantee one-time processing. - Quote Multi-Word Phrases: Wrap phrases in double quotes (
subject:"Your Security Code").
