You want to find every email about invoices — not just count them, but see a scannable list. What Gmail feature would you reach for in the web client?
The search bar at the top. I'd type something like invoice and Gmail filters the list for me.
Same idea from Python. GMAIL_FETCH_EMAILS accepts a query parameter that uses the exact syntax of Gmail's search bar. from:boss@co.com, subject:invoice, is:unread — every operator you know in the UI works here too:
result = toolset.execute_action(Action.GMAIL_FETCH_EMAILS, {"query": "is:unread"})
messages = result.get("messages", [])
Once I have messages, how do I turn that list of dicts into a list of readable previews?
One line — a list comprehension pulls the snippet off each message into a new list. Same safe .get() pattern, just inside a comprehension:
def search_subject_lines(query: str) -> list:
result = toolset.execute_action(Action.GMAIL_FETCH_EMAILS, {"query": query})
messages = result.get("messages", [])
return [m.get("snippet", "") for m in messages]
Why send the query to Gmail instead of fetching everything and filtering in Python?
Cost. If the inbox has 5,000 messages, filtering locally means downloading all 5,000 first — slow, quota-heavy, pointless. Server-side filtering pulls only the hits across the network. Always filter where the data lives.
So the list that comes back is plain Python — I can sort it, count it, loop over it, drop it into the next function?
The API complexity ends at .execute_action. After that it is a list of strings, and every tool you already own applies.
TL;DR: Let Gmail filter on its servers — pass a query, keep the response small.
[m.get("snippet", "") for m in messages] turns dicts into strings.get("messages", []) returns [], comprehension yields []| Query | Matches |
|---|---|
from:boss@co.com | emails from one sender |
subject:invoice | subject contains "invoice" |
is:unread has:attachment | unread with attachments |
You want to find every email about invoices — not just count them, but see a scannable list. What Gmail feature would you reach for in the web client?
The search bar at the top. I'd type something like invoice and Gmail filters the list for me.
Same idea from Python. GMAIL_FETCH_EMAILS accepts a query parameter that uses the exact syntax of Gmail's search bar. from:boss@co.com, subject:invoice, is:unread — every operator you know in the UI works here too:
result = toolset.execute_action(Action.GMAIL_FETCH_EMAILS, {"query": "is:unread"})
messages = result.get("messages", [])Once I have messages, how do I turn that list of dicts into a list of readable previews?
One line — a list comprehension pulls the snippet off each message into a new list. Same safe .get() pattern, just inside a comprehension:
def search_subject_lines(query: str) -> list:
result = toolset.execute_action(Action.GMAIL_FETCH_EMAILS, {"query": query})
messages = result.get("messages", [])
return [m.get("snippet", "") for m in messages]Why send the query to Gmail instead of fetching everything and filtering in Python?
Cost. If the inbox has 5,000 messages, filtering locally means downloading all 5,000 first — slow, quota-heavy, pointless. Server-side filtering pulls only the hits across the network. Always filter where the data lives.
So the list that comes back is plain Python — I can sort it, count it, loop over it, drop it into the next function?
The API complexity ends at .execute_action. After that it is a list of strings, and every tool you already own applies.
TL;DR: Let Gmail filter on its servers — pass a query, keep the response small.
[m.get("snippet", "") for m in messages] turns dicts into strings.get("messages", []) returns [], comprehension yields []| Query | Matches |
|---|---|
from:boss@co.com | emails from one sender |
subject:invoice | subject contains "invoice" |
is:unread has:attachment | unread with attachments |
Create a free account to get started. Paid plans unlock all tracks.