Gmail — Get emails

Gmail — Get emails

Type: gmail-get-emails  ·  Package: Gmail v1.0.4  ·  Output: List<Dictionary<string,object>>

Searches the mailbox using Gmail’s search syntax and returns the list of matching messages. It is usually the activity a process starts with: find the emails to process, then loop over them.

How it works

It works on the session created with Gmail — Connect. Pass it in the session parameter, or place this activity inside the body of Gmail — Connect to inherit it automatically.

• query accepts the same syntax as Gmail’s search box: is:unread, from:, to:, subject:, has:attachment, filename:pdf, label:, in:inbox, after:2026/10/01, before:, newer_than:7d, older_than:1y… Empty = all mail.
• labelIds restricts to emails that have all the given labels, by ID (INBOX, UNREAD, STARRED, Label_123…). To use label names, put them in the query (label:Suppliers) or look up the IDs with Get labels.
• As in Gmail, Trash and Spam are not included unless you ask for them in the query (in:trash, in:spam, in:anywhere).
• Results come in Gmail’s order: newest first.

The activity runs a single query, and Gmail returns at most 500 emails per query; it does not request further pages. For large volumes, work in batches: label, archive or mark as read what you processed and query again. Each email is fetched with its own request, so a high maxResults and includeBody make the activity slower.

Required parameters

None.

Optional parameters

Parameter	Type	Default	Description
session	ZoanGmailSession	—	Gmail — Connect session (inherited inside body).
query	string	—	Gmail search (same syntax as the mailbox search box). Empty = all mail. E.g.: is:unread from:supplier@example.com.
maxResults	int	25	Maximum number of emails to return (Gmail accepts up to 500). An empty, non-numeric or less-than-1 value uses 25.
includeBody	bool	false	If true, includes each email’s body and attachment info (body, bodyHtml, attachments keys).
labelIds	string | List	—	Label ID(s) the emails must have (e.g. INBOX, UNREAD). Text separated by commas or semicolons, or a list.

Output

Returns a List<Dictionary<string,object>>: a list where each item is an email with these keys.

Key	Type	Content
id	string	Message ID. It is the input of the other activities and does not change when you label or archive.
threadId	string	ID of the conversation it belongs to.
from	string	From header as is, with name and address: Ana Perez <ana@example.com>. The bare address is what’s between < and >.
to	string	To header as is (several addresses separated by commas).
cc	string	Cc header as is, or null if none.
subject	string	Subject.
date	string	Date header as is, in email format (Wed, 15 Oct 2026 09:03:22 -0500).
snippet	string	Excerpt from the beginning of the message, as plain text.
labels	List<string>	IDs of the email’s labels (INBOX, UNREAD, IMPORTANT, Label_…).
unread	bool	true if the email is unread.
body	string	Only with includeBody. Plain-text body; if the email only has HTML, that HTML with the tags stripped; "" if there is no body.
bodyHtml	string	Only with includeBody. HTML body, or null if the email has none.
attachments	List<Dictionary>	Only with includeBody. One item per attachment with filename, mimeType, size (bytes) and attachmentId.

Without includeBody, the body, bodyHtml and attachments keys do not exist in the dictionary. If nothing matches, it returns an empty list (it does not fail).

Common errors

Message	Cause and fix
No Gmail session available. …	You didn’t pass session and the activity is not inside Connect’s body.
Gmail 400 error, or an empty list when you expected emails	labelIds contains label names instead of IDs. Use the IDs from Get labels, or label:Name in query.
Request had insufficient authentication scopes.	The connection lacks Gmail read permission. Check its scopes in Zoan Cloud.

Example

Gmail — Connect   credential = credential("gmail-support")
 └─ body:
      Gmail — Get emails   query = "is:unread has:attachment subject:invoice"   maxResults = 50   → output: pending
      For each   email in pending
       └─ Gmail — Download attachments   id = email["id"]   folder = "C:\invoices\inbox"   → output: files
          Log   message = str(email["subject"]) + ": " + count(files) + " attachment(s)"
          Gmail — Mark read/unread   id = email["id"]

Related activities

• Gmail — Connect — open the session.
• Gmail — Get email by ID — get a full email.
• Gmail — Download attachments — save an email’s attachments.
• All Gmail activities