Outlook 365 — Get emails

Outlook 365 — Get emails

Type: outlook365-get-emails  ·  Package: Outlook 365 v1.0.4  ·  Output: List<Dictionary<string,object>>

Searches emails in the mailbox (or in a specific folder) and returns the list of matching messages. It is usually the activity a mail process starts with: find what is pending, then loop over the list.

How it works

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

Narrow it down with folder (a well-known name such as inbox or a folder ID); without folder it searches every folder in the mailbox, including Sent Items and Deleted Items. There are three ways to filter, and they combine like this:

What you set	How it is queried	Result order
subject and/or search	Graph search ($search). If you set both, they are combined with AND. filter is ignored.	Graph’s own order (search results cannot be sorted).
Only filter	OData filter ($filter).	Newest first (receivedDateTime descending).
Nothing	Every email in scope.	Newest first.

unreadOnly adds to any of the three. Without a search it is added to the filter (isRead eq false) and Graph applies it. With a search, Graph does not accept a filter at the same time, so the activity asks for more emails than you need (maxResults × 4, up to 200), drops the read ones and keeps the first maxResults. If that page came back full, it writes a warning to the log: there may be more unread emails beyond it; narrow the search or remove it so Graph can filter server-side.

subject matches text inside the subject (any double quotes you type are removed). It is the way to match part of a subject: Graph’s $filter does not support contains() for emails.

The activity runs a single query: it does not request further pages. For large volumes, work in batches: mark, categorize or move what you processed and query again.

Required parameters

None.

Optional parameters

Parameter	Type	Default	Description
session	ZoanOutlookMailSession	—	Outlook 365 — Connect session (inherited inside body).
folder	string	—	Folder: well-known name (inbox, sentitems, drafts, deleteditems, archive, junkemail) or folder ID. Empty = all folders. Searches only that folder, not its subfolders.
subject	string	—	The subject contains this text (e.g. Invoice). Runs as a search ($search) on the subject.
unreadOnly	bool	false	Return only unread emails.
search	string	—	Graph full-text search ($search, KQL syntax), e.g. from:supplier@example.com invoice or hasAttachments:true. Do not use double quotes inside it.
filter	string	—	OData filter ($filter), e.g. isRead eq false, hasAttachments eq true, startswith(subject,'Invoice'), receivedDateTime ge 2026-10-01T00:00:00Z. Supports eq, ne, startswith, date comparisons and and/or; it does not support contains(). Ignored when you use search or subject.
maxResults	int	25	Maximum number of emails. An empty, non-numeric or less-than-1 value uses 25.
includeBody	bool	false	Include each email’s body (body and bodyType keys). Makes the response heavier; turn it on only if you will read the content.

Output

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

Key	Type	Content
id	string	Graph message ID. It is the input of the other activities. It changes if the email is moved to another folder.
subject	string	Subject.
from	string	Sender address (ana@example.com).
fromName	string	Sender display name.
to	List<string>	Recipient addresses.
cc	List<string>	Cc addresses (empty list if none).
receivedDateTime	string	Received date and time in ISO 8601 with offset, in UTC (2026-10-15T14:03:22.0000000+00:00).
preview	string	First characters of the body, as plain text.
isRead	bool	true if already read.
hasAttachments	bool	true if it has attachments.
categories	List<string>	Assigned Outlook categories.
webLink	string	Link that opens the email in Outlook on the web.
body	string	Body content (HTML or text, see bodyType). null when includeBody is false.
bodyType	string	Html or Text. null when includeBody is false.

If nothing matches, it returns an empty list (it does not fail). Loop over it with For each and read by key (email["subject"]).

Common errors

Message	Cause and fix
Microsoft Graph does not support contains() in $filter for messages; …	The filter uses contains(). To match part of the subject use subject; for other searches, search.
No Outlook 365 session available. …	You didn’t pass session and the activity is not inside Connect’s body.
Graph error ErrorInvalidIdMalformed or ErrorItemNotFound when reading the folder	The folder value is neither a well-known name nor a valid folder ID.
Graph BadRequest error on the filter	The OData expression is invalid (use single quotes for text and Graph property names: isRead, subject, receivedDateTime…). Try without filter first to isolate the problem.

Example

Process the unread invoices in the inbox, save their attachments and archive them:

Outlook 365 — Connect   credential = credential("m365-invoices")
 └─ body:
      Outlook 365 — Get emails   folder = "inbox"   subject = "Invoice"   unreadOnly = true   maxResults = 50   → output: pending
      For each   email in pending
       └─ Outlook 365 — Download attachments   id = email["id"]   folder = "C:\invoices\inbox"   → output: files
          Log   message = str(email["fromName"]) + ": " + count(files) + " attachment(s)"
          Outlook 365 — Move   id = email["id"]   destination = "archive"

With an OData filter (newest first):

Outlook 365 — Get emails   folder = "inbox"   filter = "hasAttachments eq true and receivedDateTime ge 2026-10-01T00:00:00Z"   → output: withAttachments

Related activities

• Outlook 365 — Get email by ID — get a full email.
• Outlook 365 — Download attachments — save the attachments.
• Outlook 365 — Move — archive the processed email.
• All Outlook 365 activities