Microsoft Mail Listener
Microsoft Mail Listener
The Microsoft Mail Listener is specifically designed to fetch mail from Exchange Online (as part of Microsoft 365) using modern authentication. The generic ConnectPlaza E-Mail Listener is at the time of writing not compatible with modern authentication and as such is not suited to fetch mail from Exchange Online.
Please note that before you can use the Microsoft Mail Listener you need to register an application within Azure Active Directory. See Microsoft mail app registration instructions.
One particularly important attribute is the Mapping Type. If set to TO_CONNECT_MESSAGE_PARTS, this component will map the body and attachments to separate MessageParts in the outgoing ConnectMessage, as illustrated below.
The Microsoft Mail Listener maps the headers to, from, replyTo, cc, subject, importance, receivedDateTime, sentDateTIme and id to the outgoing ConnectMessage prefixing each with the configured Mail Header Prefix (by default "microsoft.mail.listener."). Date-time information is always in epoch seconds.
The body of the mail in most cases contains either plain text or HTML. A contentType header (prefixed by Mail Header Prefix) is added to the ConnectMessage that contains the associated MIME type which will be text/plain, text/html or application/octet-stream (if the precise body content-type is unknown).
In addition, if the Mapping Type has been set to TO_CONNECT_MESSAGE_PARTS, the contentType, lastModifiedDate, isInline, size and name properties of attachments are mapped to the individual outgoing MessageParts (prefixed by Mail Header Prefix) as well as to the ConnectMessage (prefixed by the Mail Header Prefix plus ".<MessagePart name>").
NOTE: Signed EMAIL is NOT supported!
In the table below, you will find an explanation of the component attributes. All attributes with a ‘*’ are mandatory.
|
Attribute |
Description |
|
Name* |
By default, we fill this out with the technical ‘tag’, followed by a serial number. Changing the name is optional. |
|
Enabled |
Check this box if you want this consumer to be enabled. |
|
Consumer Autostart |
Consumer will be started at startup of the interface. |
|
MessagePart Out |
The name of the MessagePart in the outgoing ConnectMessage. This will contain the mail body unless the Mapping Type is set to TO_SINGLE_JSON_PART in which case it contains a JSON representation of the mail. |
|
Client ID* |
The client id of the registered app. |
|
Client Secret* |
The client secret of the registered app. |
|
Tenant ID* |
The tenant ID. |
|
User Account* |
The email address, ID or principal name of the mailbox owner. |
|
Mail Folder Name* |
The name of the mail folder to fetch mail from. You can use a forward slash to reference child folders e.g. foo/bar/baz refers to the mail folder baz with parent mail folder bar whose parent (root) folder is foo. |
|
Mark Mail as Read |
Mark fetched mail as read. |
|
Delete Mail |
Delete mail on the server as soon as it is fetched. Note that this happens after marking mail as read (if enabled). |
|
Followup Flag Action |
The followup flag action to take as soon as the mail is fetched. FLAG_MAIL - Raise the followup flag on fetched mail. MARK_AS_COMPLETED - Mark fetched mail as completed. REMOVE_FLAG - Remove the followup flag from fetched mail. DO_NOT_CHANGE - Do not change the followup flag. |
|
Fetch Only Unread Mail |
Fetch only unread mail. |
|
Filter Expression |
The mail filter expression to use. The syntax is based on Microsoft Graph filter query syntax, see https://docs.microsoft.com/en-us/graph/query-parameters#filter-parameter for more information. |
|
Polling Strategy |
The manner in which we specify when we want to poll the mailbox. SIMPLE - Poll the mailbox every few minutes. CRON - Poll the mailbox based on a Cron expression. |
|
Polling Rate in Minutes |
Only available if Polling Strategy is set to SIMPLE. The time to wait between each poll in minutes. |
|
Polling Cron Expression |
Only available if Polling Strategy is set to CRON. The Cron expression determining when to poll the mailbox. |
|
Limit Poll Size |
Should the number of messages fetched in a single poll be limited? |
|
Poll Size |
Only available if Limit Poll Size is set to true. The number of messages that should be fetched every time the mailbox is polled. |
|
Mapping Type |
Determines how fetched mail is mapped to a ConnectMessage. TO_SINGLE_JSON_PART - Map the mail to a single outgoing MessagePart containing a JSON represenation of the mail (including attachments, headers and metadata). See https://docs.microsoft.com/en-us/graph/api/resources/message?view=graph-rest-1.0 for more information. TO_CONNECT_MESSAGE_PARTS - Map the mail to one or more MessageParts. One containing the body, the others containing attachments. |
|
Attachment Inclusion Strategy |
Only available if Mapping Type is set to TO_CONNECT_MESSAGE_PARTS. The manner in which to specify which attachments should be mapped to MessageParts. ALL - Include all attachments. NONE - Include no attachments. NAME_REGEX - Only include attachments if their name matches a specified regex. CONTENT_TYPE_REGEX - Only include attachments if their content-type matches a specified regex. |
|
Attachment Inclusion Name Regex |
Only available if Attachment Inclusion Strategy is set to NAME_REGEX. Only map an attachment to a MessagePart if its name matches the regex. |
|
Attachment Inclusion Content-Type Regex |
Only available if Attachment Inclusion Strategy is set to CONTENT_TYPE_REGEX. Only map an attachment to a MessagePart if its content-type matches the regex. |
|
Default Attachment Charset Encoding |
Only available if Mapping Type is set to TO_CONNECT_MESSAGE_PARTS. The default charset encoding to use when mapping an attachment containing text to a MessagePart. Note that if the attachment content-type contains a charset, that will take precedence. |
|
Attachment Text Content-Type Regex |
Only available if Mapping Type is set to TO_CONNECT_MESSAGE_PARTS. Any attachment content-types that match this regex will be mapped to a text-based MessagePart. Note that if a content-type does not match this regex but does define a charset attribute, it is considered to be a text-based content-type. |
|
Attachment Naming Strategy |
Only available if Mapping Type is set to TO_CONNECT_MESSAGE_PARTS. Determines how the MessageParts containing the attachments are named. USE_ATTACHMENT_NAME - Use the attachment name as the MessagePart name. PREFIX_POSTFIX - Define a prefix and postfix which is used to generate names of the form <prefix>n<postfix> with n being an increasing number starting at zero, i.e. 0, 1, 2, 3, etc.. |
|
Attachment MessagePart Prefix |
Only available if Attachment Naming Strategy is set to PREFIX_POSTFIX. The prefix to use when generating MessagePart names for attachments. |
|
Attachment MessagePart Postfix |
Only available if Attachment Naming Strategy is set to PREFIX_POSTFIX. The postfix to use when generating MessagePart names for attachments. |
| Mail Header Prefix |
The prefix to use for mapped mail header names e.g. "from" becomes "microsoft.mail.listener.from". |
| Sort By |
Determines which mail should first be sent to the rest of the flow as ConnectMessage. |
| Enable Extra Logging (advanced attribute) |
Enables extra logging. |
| Page Size (advanced attribute) |
The page size of the response, i.e. the number of mails retrieved in a single request/response pair. Note that a single poll can consist of multiple request/response pairs. This setting should only be adjusted if you encounter HTTP error code 504 (Gateway Timeout). |
|
Description |
Description of the specific consumer. This is for documentation purposes. |