Mailbox listeners – processing incoming mail¶

A mailbox listener watches a folder of a mailbox and runs actions for the mails that arrive there – for example to create a ticket from a mail or to add a customer's reply to the ticket it belongs to. This chapter describes how to set one up, how a mail finds its record and what happens to the mail afterwards.

It is intended for administrators who connect nexxcite to a mailbox.

1. Mailbox listeners at a glance¶


Purpose	Runs actions for incoming mails of a mailbox folder
Typical use	Creating records from mails, adding replies to the record they belong to, importing data sent by mail
Where	Admin Studio → Automation → Mailbox Listeners
Related	Actions, Global settings – the conversation id, Background processing

Summary¶

A listener reads the unread mails of one folder, about every 20 seconds, up to 10 mails per round, newest first.
For each mail, its processing rules are checked in order. The first rule whose action runs wins.
A rule finds the record a mail belongs to through the conversation id in the mail or through a query, and runs one action when it found a record and another when it did not.
Afterwards the mail is marked as read, moved or deleted – depending on "On Success" and "On Error". With "None", the mail stays unread and is processed again in the next round.

How it works¶

every ~20 s   unread mails of the folder (max. 10, newest first)
                 │
                 ▼
         "Ignore Mails" true? ──yes──► skipped, stays unread
                 │ no
                 ▼
         rule 1, rule 2, …   (the first rule whose action runs wins)
           1. find the record: conversation id, then the identification query
           2. record found    → condition → action on the record
              no record found → condition → action without a record
                 │
                 ▼
         action ran without error → "On Success"
         action failed            → "On Error"
         no rule applied          → mail stays untouched (unread)

2. Setting up¶

What you need¶

Item	Where
A mail account – "IMAP Credentials" or "Exchange Online Credentials"	Admin Studio → Access → Credentials, see API access and credentials
A user the rules and their actions run as	Admin Studio → Access → Users – preferably a technical user
The actions that process the mails	Admin Studio → Automation → Actions
A server that polls mailboxes	`ApplicationServer:ProcessMailboxListeners = true` (default), see Installation and configuration

Use an account that may read the folder and – for "On Success" and "On Error" – mark, move and delete mails in it. For Exchange Online, the app registration behind the credentials needs the corresponding permissions on the mailbox; the exact permissions are set in Microsoft Entra ID and are described in Microsoft's documentation.

Steps¶

Create the listener in Admin Studio → Automation → Mailbox Listeners.
On the tab "General", choose "Identity" and "Mailbox Credentials". Once the credentials are chosen, "Folder" lists the folders of the mailbox – choose the one to watch.
Set "On Success" and "On Error" – normally "MarkAsRead" or "MoveToFolder".
On the tab "Processing Rules", add at least one rule with the add button.
Switch "Enabled" on and save.

nexxcite does not test the connection when you save. Problems show up with the first poll, under Monitoring → Servers on the card of the polling server and under Monitoring → Background Processes.

3. Settings of the listener¶

Tab "General":

Setting	Meaning	Default / Required
"Identity"	The user the rules and their actions run as. Its roles decide which records the rules can find and change.	Required. Without it, the listener does not poll.
"Enabled"	Switches polling on. A new listener is off.	off
"Mailbox Credentials"	The mail account: "IMAP Credentials" or "Exchange Online Credentials".	Required
"Folder"	The folder that is watched. The list is read from the mailbox.	Required
"On Success"	What happens to a mail whose action ran without error: "None", "MoveToFolder", "Delete", "MarkAsRead".	"None"
"Sucess Folder"	Target folder for "MoveToFolder" after success. (The label is spelt this way in the application.)	Required for "MoveToFolder"
"On Error"	What happens to a mail whose action failed – same choices.	"None"
"Error Folder"	Target folder for "MoveToFolder" after an error.	Required for "MoveToFolder"
"Ignore Mails"	A condition per mail. If it is true, the mail is skipped – not processed and left unread.	empty = no mail is skipped
"Store Execution Log"	Whether the log of a round is kept: "Inherit (use the next level)", "Never", "On failure or warnings", "Always".	"Inherit (use the next level)"

Choose "On Success" deliberately. With "None", a processed mail stays unread and is processed again in every round – every 20 seconds, with all the consequences of its action (for example a new record each time).

Operation	Effect
"None"	The mail stays as it is – unread.
"MarkAsRead"	The mail is marked as read and stays in the folder.
"MoveToFolder"	The mail is marked as read and moved into the chosen folder.
"Delete"	The mail is deleted permanently – not moved into the deleted items.

4. Processing rules¶

Tab "Processing Rules". Each rule has these settings:

Setting	Meaning	Default / Required
"Entity"	The entity whose records the rule looks for. A rule without an entity is skipped.	Required
"Use Conversation ID"	Looks for the record through the conversation id in the mail (section 5).	off
Record identification (query)	A query on the entity that finds the record of the mail – shown below the switches once the entity is chosen. Its conditions can use the values of the mail, for example the subject.	empty
"Require Record"	The rule only applies when a record was found.	off
"Condition"	With "Require Record": a condition checked against the found record. Without: a condition checked without a record. Empty means always.	empty
"Action"	With "Require Record": the action that runs on the found record. Without: the action that runs when no record was found – for example to create one.	Required

The values of the mail¶

Conditions, the identification query and the actions can read the mail:

In the listener editor	In the action editor	Content
"From Address"	"Received E-Mail From Address"	Sender
"To Addresses", "CC Addresses", "BCC Addresses"	"Received E-Mail To Addresses" etc.	Recipients, separated by `;`
"Subject"	"Received E-Mail Subject"	Subject
"Plain Text Body" / "Html Body"	"Received E-Mail Plain Body" / "Received E-Mail HTML Body"	The body – only one of them is filled, depending on the format of the mail
"Importance"	"Received E-Mail Importance"	"Low", "Normal" or "High"
"Has Attachments"	"Received E-Mail Has Attachments"	true / false
–	"Received E-Mail Attachments"	The attachments as JSON: a list with `Name`, `MimeType` and `Base64Data` per file
–	"Received E-Mail DateTime"	When the mail was received

In the action editor, add these variables under "Enabled Special Variables" to have them offered in the expressions of the action. They are passed to the action either way.

Attachments: to keep an attachment, read Base64Data from the JSON and store it with the command "Add File" on a record (see Actions). The content of every attachment is passed to the action in full, so very large attachments make the processing slow.

Order of evaluation¶

For each mail:

"Ignore Mails" is checked. If it is true, the mail is skipped.
The rules are checked in the order of the list. For each rule:
With "Use Conversation ID", the record of the conversation is looked for (section 5).
If none was found and a query is set, the query runs. It must find exactly one record; no record or more than one count as "no record".
Record found: the rule applies if it has an action for records and its condition holds. The action runs on the record.
No record found: with "Require Record", the rule does not apply. Otherwise it applies if it has an action without a record and its condition holds.
The first rule whose action runs ends the processing of the mail. The remaining rules are not checked.
If no rule applied, the mail stays untouched – neither "On Success" nor "On Error" is applied.

5. Matching a mail to its record¶

Through the conversation id¶

When an action sends a mail with "Send E-Mail", nexxcite records it under a conversation id. With the setting "Conversation Id" of the command ("End of the subject" or "End of the body"), the id is written into the mail, for example [NXC-K7M2Q9XT4BVR]. Most mail clients keep the subject and quote the body in a reply, so the id comes back.

A rule with "Use Conversation ID" looks for this id:

first in the subject,
then in the body (an HTML body is reduced to its text first).

The id leads to the record the original mail was sent from. The rule uses that record only if

it belongs to the "Entity" of the rule – otherwise a later rule for the right entity can take it, and
the "Identity" of the listener may read it.

Otherwise the rule falls back to its query, as if there were no id.

The prefix (NXC by default) is set in the global settings under "Conversation Id Prefix". Only ids with the current prefix are recognised. See Global settings.

Through a query¶

Without a conversation id – a new mail, or a reply in which the id was removed – a query can find the record, for example by an order number in the subject or by the sender's address. The query must find exactly one record.

Example: the entity "Order" has a field "Order number". The query "Order number equals" an expression that extracts the number from "Subject" finds the order for a mail with the subject "Question about order 4711".

6. Errors and repetitions¶

Situation	What happens to the mail	In the history
The action ran without error	"On Success"	"Processed"
The action failed with an unexpected error	"On Error"	"Processed with errors"; the round is "Failed"
The action finished, but reported errors in its protocol	"On Success" – the mail counts as processed	"Processed with errors"; the round is "Failed"
No rule applied	untouched, stays unread	"No rule matched"; the round "Succeeded with warnings"
Skipped by "Ignore Mails"	untouched, stays unread	"Ignored"
The mail could not be processed at all	untouched	"Failed"
The mailbox cannot be reached, or the listener is incomplete (no identity, credentials or folder)	–	The round fails. The first error, a changed error and then once per hour are recorded.

Mails that stay unread come back. A mail left unread – because of "None", because no rule applied or because it was ignored – is fetched again in every round. Since each round takes the 10 newest unread mails, ten or more such mails at the top of the folder keep older unread mails from being reached at all. Make sure every mail leaves the unread state: add a last rule without conditions that catches everything else, or move such mails out of the folder by a mail rule of the mail server.

A listener does not start a new round while its previous round is still running. If a round hangs, the next one starts after about 5 minutes.

7. Execution history and monitoring¶

Where	What
Monitoring → Background Processes	Every round that handled at least one mail or failed, kind "Mailbox listener": one line per mail with sender, subject, time of receipt, number of attachments, the rule that handled it and why the other rules did not apply, the record and how it was found (conversation id or query), the action with its protocol, the result and the operation afterwards.
Communication → Incoming E-Mails	Every mail the listener fetched, with its content, the result, the action of the rule that applied and the record – see Communication. A mail that is fetched again in later rounds is listed once.
Monitoring → Servers and Monitoring → Background Processes → "Overview"	On the card of the polling server, per listener: state, last poll, mails handled since start, last error. On the overview of Background Processes, "Poll now" polls at once.

Rounds without mails are not recorded – that would be one line every 20 seconds. The body of a mail is not stored in the history of the rounds; it is kept with the mail under Communication → Incoming E-Mails.

A server is shown as "Degraded" when a listener failed on its last poll, and as "Unhealthy" when a listener failed 10 times in a row. See Monitoring.

8. Which server polls – and when changes take effect¶

Only servers with ApplicationServer:ProcessMailboxListeners = true poll mailboxes. With several servers, exactly one may have this setting. See Running several servers.

Change	Takes effect
Rules, actions, operations, folder	With the next round. Each round reads the current listener.
A new listener, or one switched on, saved in the editor	Immediately – if the server serving your browser tab polls mailboxes. Otherwise when the polling server restarts.
A new listener that arrives in another way (AI assistant, sketch import)	When the polling server restarts.
"Enabled" switched off	Only when the polling server restarts. Until then, the listener keeps polling and processing mails.
Deleted	Polling stops as soon as the deletion is published. With several servers, the polling server learns about a deletion published on another server through the message bus (see Running several servers). Without a message bus, polling stops only when the polling server restarts; until then, a failed round is recorded (once, then once per hour).

To stop a listener at once, take its mails away from it as well: remove the rules or the action, or restart the polling server after switching it off.

Saving a listener registers its polling immediately, even while a sketch is open. A round always reads the published listener, so a new listener saved into a sketch only reports that it does not exist until the sketch is published.

9. Permissions¶

Permission	Allows	Granted by
"Open Mailbox Listener Manager"	Seeing the collection in the Admin Studio	System Administrator
"Add Mailbox Listener"	Creating listeners	System Developer
"Edit Mailbox Listener"	Changing listeners	System Administrator
"Delete Mailbox Listener"	Deleting listeners	System Administrator
"View Background Processes"	Seeing the rounds and mails	System Administrator
"View Communication"	Seeing the fetched mails with their content	System Administrator
"Background Job Administration"	"Poll now"	System Administrator

"Add Mailbox Listener" belongs to "System Developer", unlike the other three. A user with only "System Administrator" can change listeners but not create new ones.

10. Limitations¶

Mails are fetched about every 20 seconds, at most 10 per round. A mailbox that receives more mails than that is worked off with a delay.
Only unread mails are fetched. A mail that someone opens in a mail client before the listener got to it is not processed.
Switching a listener off takes effect only after the polling server has restarted (section 8).
Exchange Online: in our reading of the current version, attachments of mails fetched from Exchange Online do not reach the rules – "Has Attachments" is false and the attachment list is empty. With IMAP, attachments are passed. Test this with your mailbox before you rely on it.
Exchange Online: the folder list offers the folders on the top level of the mailbox.
Of a mail with both an HTML and a text part, only one body is passed.
Changing the "Conversation Id Prefix" stops replies to mails that were sent with the previous prefix from being matched through the conversation id.

11. Frequently asked questions¶

The same mail creates a new record every 20 seconds. Why? "On Success" is "None", so the mail stays unread and is processed again in every round. Choose "MarkAsRead", "MoveToFolder" or "Delete".

A reply was not added to its ticket. What should I check? The details of the round in Monitoring → Background Processes: per mail, the rule trace says why each rule did not apply. Common causes: the reply no longer contains the conversation id, the original mail was sent without "Conversation Id", the rule's entity is a different one, or the "Identity" of the listener may not read the ticket.

Can a listener watch several folders? No. Create one listener per folder.

Can I test a listener without waiting? Yes, "Poll now" on the card of the polling server under Monitoring → Background Processes → "Overview", or in the details of an earlier round (requires "Background Job Administration"). A manual poll is recorded even when it finds no mail.

Is the mail body stored in nexxcite? Yes. Every fetched mail is recorded with sender, recipients, subject, body and the names of its attachments and listed under Communication → Incoming E-Mails. The attachments themselves are only kept if your actions store them. The history of the rounds keeps sender, recipients, subject and the names of attachments.