Microsoft Email Listener

Microsoft 365 mailboxes store business email, folder structures, message content, and attachments that teams use for communication, intake, and operational processing.

The Microsoft Email Listener Node polls a mailbox folder through Microsoft Graph and emits unread messages into a Workflow, either one item per email or one item per attachment. Use it when a Workflow needs to react to inbound mailbox traffic such as invoices, support requests, or approval emails.

Revision History

0.1.0.0 - Rebased the Node package version after the V2 overhaul review.
0.0.0.29 - Standardized the public V2 help article.
1.0.0.0 - Initial release.
1.0.0.9 - Fixed shared OAuthConnection lock handling.
0.0.0.12 - Node name correction.
0.0.0.26 - Added support for nested mailbox folder paths in the listener folder settings.

Connection

Use the Microsoft Graph Email Connection to authorize mailbox access and, when needed, target a specific mailbox instead of the authenticated user mailbox.

Property	Type	Description
Tenant Id	String	The Microsoft Entra ID tenant identifier, or common for a multi-tenant sign-in flow.
Client Id	String	The application ID from your Microsoft Entra ID app registration.
Client Secret	Masked	The client secret generated for the app registration.
Access Token	Masked	The OAuth access token returned after authorization.
Refresh Token	Masked	The OAuth refresh token used to renew access when Microsoft returns one.
Scopes	String	The OAuth scopes requested during authorization. The default is offline_access https://graph.microsoft.com/.default.
Mailbox	String	The optional mailbox address or UPN to monitor. Leave this empty to use the authenticated user mailbox.

Setup Notes

• Register an application in Microsoft Entra ID with mail permissions such as Mail.Read or Mail.ReadWrite.
• Grant admin consent when your tenant requires it, or make sure the signed-in user has already consented to the requested permissions.
• Configure the Connection with Tenant Id, Client Id, and Client Secret, then complete the OAuth authorization flow so Access Token and Refresh Token are populated.
• Set Mailbox only when you need to monitor a specific mailbox. Leave it empty when you want the Node to use the authenticated user mailbox.
• Make sure the monitored, processed, and error folders already exist before you run the Node.
• You can supply folder settings as a well-known top-level folder such as Inbox, a direct Microsoft Graph folder identifier, or a nested path such as Inbox/Invoices.

Methods

This Node exposes one listener method that polls a mailbox folder and emits mailbox payloads to a Workflow.

Listen

Use this method when you want a Workflow to react to unread messages in a Microsoft 365 mailbox folder.

Parameter	Type	Description
Connection	Connection	The Microsoft Graph Email Connection that contains the mailbox authorization details.
MonitoredFolder	String	The folder to poll for unread messages. You can use a well-known folder such as Inbox, a direct Graph folder ID, or a nested path such as Inbox/Invoices.
ProcessedFolder	String	The optional folder to move successfully processed messages to. You can also use a nested path. Leave this empty when you want successful messages marked as read instead.
ErrorFolder	String	The optional folder to move failed messages to. You can also use a nested path. Leave this empty when you want failed messages to remain in the monitored folder.
FireMethod	String	Controls how the Node emits results. Use PerMessage to emit one payload per email, or PerAttachment to emit one payload per attachment.

Return	Type	Description
Response	Array	An emitted sequence of mailbox payloads. Each payload includes MessageId, Sender, Recipients, Subject, Body, IsBodyHtml, EmailDate, and Attachments. PerMessage emits one payload with all resolved attachments for the message, while PerAttachment emits one payload per attachment.

Usage Notes

• The listener polls every 5 seconds until the Workflow stops or runtime cancellation is requested.
• The Node resolves nested folder paths one segment at a time from the mailbox root. For example, Inbox/Invoices resolves Inbox first and then Invoices below it.
• When ProcessedFolder is empty, successful messages are marked as read instead of being moved.
• When ErrorFolder is empty, messages that fail during payload construction remain in the monitored folder.
• Empty polls are a normal outcome and do not emit payloads.
• If Microsoft Graph returns an error on the first unread-message poll, the Node surfaces that provider failure instead of converting it into an empty successful result.

Known Issues

• Nested folder paths support / delimiters only. The Node does not perform a recursive mailbox-wide search by leaf folder name.