Simulators

Search

GET /gmail/v1/users/me/messages and GET /gmail/v1/users/me/threads take q, the grammar of Gmail’s search box, and filter the busy inbox the way Gmail does. Find mail by attachment, folder, label, phrase and subject:

curl -s -X POST "$RYSTIC_URL/_rystic/scenario" -d '{"name":"gmail_busy_inbox"}' -o /dev/null
G=(-H 'Authorization: Bearer ya29.placeholder')
curl -s -G "$RYSTIC_URL/gmail/v1/users/me/messages" --data-urlencode 'q=has:attachment' "${G[@]}" | jq -c '{ids: [.messages[].id], resultSizeEstimate}'
# -> {"ids":["19a4c0d1e2f31003"],"resultSizeEstimate":1}
curl -s -G "$RYSTIC_URL/gmail/v1/users/me/messages" --data-urlencode 'q=in:trash' "${G[@]}" | jq -c '{ids: [.messages[].id], resultSizeEstimate}'
# -> {"ids":["19a4c0d1e2f31009"],"resultSizeEstimate":1}
curl -s -G "$RYSTIC_URL/gmail/v1/users/me/messages" --data-urlencode 'q=invoice label:receipts' "${G[@]}" | jq -c '{ids: [.messages[].id], resultSizeEstimate}'
# -> {"ids":["19a4c0d1e2f31003"],"resultSizeEstimate":1}
curl -s -G "$RYSTIC_URL/gmail/v1/users/me/messages" --data-urlencode 'q="flight ZX4821"' "${G[@]}" | jq -c '{ids: [.messages[].id], resultSizeEstimate}'
# -> {"ids":["19a4c0d1e2f31004"],"resultSizeEstimate":1}
curl -s -G "$RYSTIC_URL/gmail/v1/users/me/threads" --data-urlencode 'q=subject:standup' "${G[@]}" | jq -c '{ids: [.threads[].id], resultSizeEstimate}'
# -> {"ids":["19a4c0d1e2f30004"],"resultSizeEstimate":1}
curl -s -G "$RYSTIC_URL/gmail/v1/users/me/messages" --data-urlencode 'maxResults=100' "${G[@]}" | jq -c '{resultSizeEstimate}'
# -> {"resultSizeEstimate":8}
curl -s -G "$RYSTIC_URL/gmail/v1/users/me/messages" --data-urlencode 'maxResults=100' --data-urlencode 'includeSpamTrash=true' "${G[@]}" | jq -c '{resultSizeEstimate}'
# -> {"resultSizeEstimate":9}

Operators

q takes these, joined by an implicit AND:

bare words, and quoted phrases whose words must appear in order;
from:, to:, cc:, bcc: and subject:;
label:, category:, is: and in:;
has:attachment, filename:, larger: and smaller:;
after:, before:, older_than: and newer_than:, read against the simulator’s clock;
- for negation, OR and {…} groups.

Both lists leave trashed and spam mail out unless includeSpamTrash=true or the query names it (in:trash, in:spam, in:anywhere).

These readings are unconfirmed, meaning not yet checked against Gmail:

Query	The simulator reads it as
a date in `after:` or `before:`	midnight UTC that day: `after:` matches on or after it, `before:` before it
`K` or `M` in `larger:` or `smaller:`	1,024 or 1,048,576 bytes
`has:attachment` or `filename:`	an attachment at most two levels of parts deep, never one below that

Filters and pages

labelIds keeps only mail that carries every label named, and it combines with q. Pagination covers maxResults and pageToken.