Mail Connector
On this page
The Mail Connector turns incoming e-mail into records. It reads the messages of a mailbox, resolves each sender to a person, checks whether a message is a reply to an existing record, and then runs the operations of its job. In the usual setup, a message that resolves to an existing record runs an update operation on that record, and any other message runs a create operation. The result is a new record, such as an Incident, or an update to an existing one. For tickets, see Tickets.
You configure the Mail Connector in the Admin Center and in the Settings App; see Admin Center and Settings App. For the steps, see Set Up Mail Connector Jobs. For the rules that match, parse, and trim messages, see Incoming E-mail Processing Rules.
Mail Connector jobs
The Mail Connector runs only as a job of the Automation Server, or for a connection test. Started without either, it reports "This utility can be run by the Automation Server job only." and stops.
Each run signs in to the mailbox, processes the messages it finds, signs out, and ends. How often the mailbox is checked is therefore set by the job's schedule. Job runs do not overlap: a job that starts while another one is processing waits for it. A connection test does not wait.
One job serves one mailbox. You can create several jobs, each with its own mailbox, server type, operations, and preprocessing rules. Deleting a job also deletes its settings, its operations, and its links to preprocessing rules.
A job run uses the settings stored with the job. Two things are kept outside the job: the list of excluded addresses, in the MailConnector.cfg file, and the settings the Mail Connector uses to reach the database.
Each run records five counters: objects created, objects updated, messages, messages in the mailbox, and errors. When the job's log level is Detailed, the run also writes a debug trace for each message and, for MAPI, the messages of the MAPI engine. A connection test always writes this detail, whatever the job's log level.
Transports
The server type of a job decides how the Mail Connector connects to the mailbox and signs in:
| Server type | Settings the job needs | Sign-in |
|---|---|---|
| POP3 | Server, port, and user name | Password, optionally with Secure Password Authentication (SPA) |
| IMAP4 | Server, port, and user name | Password, optionally with SPA |
| Exchange Web Services (EWS) | User name; an Autodiscover address or the EWS URL; an Exchange version in the supported range | User name and password |
| Exchange Online | User | Microsoft OAuth sign-in, over Microsoft Graph or over EWS; Microsoft Graph is the default |
| Google Mail | Server, port, and user | Google OAuth sign-in |
| MAPI | None | The Windows session, with a named Outlook profile or the default one |
A run whose required settings are empty fails before it connects to the mail server.
When a call to the mail server fails on an EWS or Exchange Online over EWS job, the job's log shows the error message that the Exchange Managed API raised, without a prefix.
Connection security
A job uses one of four security modes: none, STARTTLS when the server offers it, required STARTTLS, or implicit SSL/TLS. Rejecting invalid certificates is a separate option, applied to POP3, IMAP4, Google Mail, and EWS. A job run uses the port stored with the job exactly as stored; a POP3, IMAP4, or Google Mail job with no port fails.
EWS jobs after TLS 1.2 is enabled
An EWS job can fail to connect, with a job log that reports that the underlying connection was closed, when TLS 1.2 is enabled on the Automation Server computer but the .NET Framework is not set to use it. When you set the Schannel registry entries for TLS 1.2 on that computer, also set the .NET Framework entries:
- On the Automation Server computer, right-click Start, click Run,
type
regedit, and click OK. - In Registry Editor, go to
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319. - Under that key, create a new DWORD value named
SystemDefaultTlsVersions. - Set
SystemDefaultTlsVersionsto1and click OK. - Go to
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319and repeat steps 3 and 4. - Close Registry Editor.
For what this value does, see Microsoft's Transport Layer Security (TLS) best practices with .NET Framework.
Mailbox folder
- IMAP4 and Google Mail. The folder name is sent to the server exactly as entered. Whether a subfolder is written with a dot or a slash follows the mail server's own convention. When the folder is empty, a job run selects no folder. When the server cannot select the named folder, the run stops with "Cannot select folder <name>."
- EWS and Exchange Online over EWS. An empty folder, or
Inboxin any letter case, means the Inbox. Any other value is a path from the root of the mailbox, with levels separated by/:Support/Escalationsis the Escalations folder inside the Support folder. Write a slash that is part of a folder name as\/. A folder that is not found raises the error "Folder <name> not found." - Exchange Online over Microsoft Graph. On a job run, an empty folder falls back to the default folder of the mail service.
- MAPI. The folder setting is ignored; the Mail Connector always reads the Inbox of the profile.
A connection test uses Inbox when the folder is empty.
Which messages a run reads
- IMAP4 reads only messages that are unread and not deleted.
- Exchange Online over Microsoft Graph reads only unread messages.
- POP3 has no read state: every message the server offers is processed, and POP3 always deletes a processed message.
- MAPI, EWS, and Exchange Online over EWS read the messages one by one, so the run log reports the number of messages processed rather than the number found.
How a message is processed
Each message goes through six steps, in this order:
| Step | What happens |
|---|---|
| 1. Resolve the sender | The sender is matched to a person, or a person is created. |
| 2. Calculate fields | Automatic-message flags are detected, then every parsing rule is evaluated, including the reference to an existing record. |
| 3. Format the body | The HTML body is normalized. |
| 4. Apply preprocessing rules | Only when ObjectRef holds a record: the message was matched to an existing record whose status is not a closed one (see Replies). |
| 5. Load message fields | Sender, addresses, subject, body, priority, and the automatic-message flags are passed to the operations. |
| 6. Run operations | The job's operations run. At least one create or update must run, or the message counts as not processed. |
Because preprocessing rules run after the reference to a record is found and before the message fields are passed on, a rule can only shorten the body that workflow receives.
Sender
The Mail Connector matches the sender to a person by name and e-mail address; see Person Matching Reference. When no person matches, it runs the job's person-create action to create one. A job without that action fails right after it connects to the database. When the action is not one of the enabled Mail Connector actions, the run fails before it processes any message, with "Person Create action not specified.", or with a message that the action is disabled when it is a disabled Mail Connector action that creates persons. This check does not reject an enabled Mail Connector action of another kind or for another class. For POP3, IMAP4, Google Mail, and Microsoft Graph jobs, an empty mailbox ends the run before this check.
Automatic messages
The Mail Connector reads every header of the message and derives two flags
from it: auto-replied and auto-generated. An auto-replied message is also
auto-generated. The headers it recognizes are Auto-Submitted,
X-Auto-Response-Suppress, X-Autorespond, X-Autoreply, Precedence,
X-Precedence, X-Autogenerated, List-Unsubscribe, List-Id, and
Feedback-ID, each with its own accepted values.
When Alloy Navigator sends notifications over SMTP, it adds such headers:
Auto-Submitted: auto-replied and X-Auto-Response-Suppress: All to
notifications sent on behalf of the Mail Connector, and
Auto-Submitted: auto-generated and X-Auto-Response-Suppress: NDR, RN, NRN
to notifications from workflow triggers, scheduled tasks, and every other
source that is not interactive. Other notifications that the Web App, the Self
Service Portal, the Import Wizard, or the mobile apps queue get neither header. A
notification from your installation that carries these headers and comes back
is therefore recognized as automatic. For notifications, see
Notifications Overview.
Parsing rules
A parsing rule cuts a value out of one part of the message: the sender, To,
Cc, the subject, the body, the subject and then the body, the priority, or
named additional headers. The value starts and ends at a text, a set of
characters, a position, or the end of the line, with options for letter case
and spaces.
The value is then checked against the rule's data type. Integer, currency, date, date and time, and float values are checked; a value that does not convert is cleared and logged, and the message is still processed. Dates are read with the date settings of the Mail Connector process. A rule of the reference-to-object type looks its value up as an object ID (OID).
Preprocessing rules
A preprocessing rule is a regular expression plus what to do with the text it matches. The rules form one shared list, and each job links the rules it uses, each with its own order and an enabled flag, so the same rule can be used by several jobs at different positions. A run applies only the enabled rules of its own job, in their order.
Attachments
Every attachment of a message reaches every operation the message runs, and
the run log records "A new attachment with the filename '<name>' and size
<bytes> has been created." for each one. The limit is the general attachment
size limit of the installation, which by default is on and set to 50 MB. An
attachment over the limit does not fail the message: its content is replaced
with the text "The file '<name>' has not been loaded because its size (<n> Mb)
exceeds the limit of <m> Mb.", .txt is added to its name, and the same text
is logged as a warning. The original message is attached as well when the job
is set to attach it.
An attachment that arrives without a file name gets a generated name with an
extension chosen from its content type, for example .jpg for image/jpeg,
.pdf for application/pdf, and .eml for message/rfc822. An unrecognized
text or message type gets .txt; any other unrecognized type gets no
extension.
Errors
An error on one message does not stop the run. Workflow errors and connection errors are logged and counted as errors; warnings are only logged. When a workflow action aborts or rejects the message, it is logged as a rejected message. Losing the database connection ends the run. Apart from warnings and a lost connection, each of these also adds an entry to the system log, attributed to the Mail Connector and to the job; see Logs.
After processing
A message counts as processed when at least one create or update operation ran:
| Action | Processed message | Message not processed |
|---|---|---|
| Mark as read | Always, except for POP3, which has no read flag | When the job marks rejected messages as read |
| Delete | For POP3, or when the job deletes processed messages | When the job deletes rejected messages |
| Purge | At the end of the run, when the job purges deleted messages, the server type is not POP3, and a message was deleted | Same as for a processed message |
For Exchange Online over Microsoft Graph, the purge option decides for each deleted message whether it is deleted permanently, and nothing is purged at the end of the run.
How records are created and updated
Operations
A job's behavior is a tree of operations of two kinds: one creates an object, the other runs an action on an existing object. Operations sit in groups of the form if, else if, and else. The usual shape is: if the message resolved to an object, branch on that object's class and run the matching update action; otherwise, create a new object.
Replies
Outgoing notifications carry a MessageID tag in the subject: a prefix, the
object's OID, and a suffix. By default the prefix is MessageID:, the suffix
is #, and the tag is added at the end of the subject; it can also be added at
the beginning, or not at all. The tag is added only when the object has an OID,
and not when the subject already contains it. When the tag is not added at all,
replies are matched only through the message IDs described below.
The first of the two ways below uses the system parsing rule, ObjectRef. In a new 2026.1 database created with the Default Workflow (see Default Workflow Configuration), ObjectRef is set to search the subject for the MessageID tag with its default prefix and suffix.
A reply is matched to a record in two ways, tried in order:
- The system parsing rule, ObjectRef, extracts the OID from the tag in the subject and looks the object up.
- If that finds nothing, the Mail Connector compares the message's
Referencesheader, and then itsIn-Reply-Toheader, with the message IDs stored for objects, and takes the most recently created matching object.
After a create operation, the Mail Connector stores the ID of the message with
the new object, provided the message's Message-ID header matches the message
ID reported for the message when it was read. After an update operation, it adds the message ID to the IDs
already stored for the object in ObjectRef; nothing is added when ObjectRef is
empty or no IDs are stored for that object yet. A later reply that refers to
one of these IDs is matched even without a tag.
ObjectRef takes the object when its status is not a closed one; a second field, InactiveObjectRef, takes it when the status is closed. With the header method, ObjectRef takes only an active object, and InactiveObjectRef takes the match only when the newest match is inactive. Either way, the tag is removed from the subject that workflow receives. An action can use either field. A match on an object whose class is not marked as visible is dropped.
Mail Connector actions in the supplied configuration
This section describes what a new 2026.1 database created with the Default Workflow contains; see Default Workflow Configuration. An upgraded database need not have these actions, and an administrator may have changed them. For how actions and their field mappings are edited, see Service Actions and Field Mappings.
The supplied configuration has these Mail Connector create actions: New Incident (Mail Connector), New Problem (Mail Connector), New Change Request (Mail Connector), New Work Order (Mail Connector), Create Service Request (Mail Connector), and New Person (Mail Connector). It also has Mail Connector update actions for Incident, Problem, Change Request, Work Order, Service Request, Approval Request, Purchase Order, and Project Task.
Their field mappings:
- A ticket create action fills the ticket's summary from Subject, its description from Content, and its requester from Sender, and also maps Auto-Generated, Auto-Replied, and InactiveObjectRef. Create Service Request (Mail Connector) also maps CC, and New Incident (Mail Connector) also maps CC and Priority.
- New Person (Mail Connector) fills the person's full name from Sender Name and the primary e-mail address from Sender E-mail.
- An update action maps Content to a Comment field, plus Sender, Sender Name, Sender E-mail, CC, Priority, Auto-Generated, and Auto-Replied. Update Approval Request (Mail Connector) maps the message body to a field it calls Content instead of Comment.
Every field mapping of these actions has its replacement mode set to Always in the supplied configuration; for the replacement modes, see Incoming E-mail Processing Rules.
What these actions leave on the record is an activity:
- A create action adds an activity with a fixed line of text, such as "New Incident created via the Mail Connector" or "New Work Order created via mail connector", and a category. For the Incident, the category is General.
- An update action adds an activity whose details are the text of the incoming message, with its own line of text and category. For the Incident, the category is Communication. The Approval Request update action writes "Request approved by <sender name>", "Request rejected by <sender name>", or "Approval updated via Mail Connector".
- Only the Incident and the Service Request update actions publish the activity.
The acknowledgement that a requester receives is sent by an e-mail notification operation within the create action, not by the Mail Connector itself.
Mail Connector in the Admin Center
The Admin Center has an E-mail Processing section with five pages: Mail Connector, MessageID Tag, Preprocessing, Parsing, and Logs. The connection test of the Admin Center always uses implicit SSL/TLS for Google Mail.
Mail Connector in the Settings App
The job window
A job opens in a window titled Mail Connector, followed by the job name in brackets for an existing job. Opening a job that is already open brings its window to the front. The window has four tabs: Settings, Processing, Preprocessing Rules, and Sessions. Sessions is unavailable until the job is saved.
The Sessions tab shows the job's Incoming Mail Log. The same log for all jobs is the E-mail Processing > Logs page of the sidebar.
Server settings
In the Mail Server group of the Settings tab, the Server Type: list offers six entries, and choosing one shows the fields of that type:
- Post Office Protocol v3 (POP3) and Internet Message Access Protocol v4 (IMAP4): Server Name:, Port:, the Secure connection options, Reject invalid certificates, Username:, Password:, and Require Secure Password Authentication (SPA). Changing the security mode switches a default port that you have not changed between 110 and 995 for POP3, and between 143 and 993 for IMAP4; any other port stays as it is.
- Messaging Application Programming Interface (MAPI): a mail profile, or Use default profile, and the profile account described below.
- Exchange Web Services (EWS): the EWS URL or the e-mail address for Autodiscover, the user name, and its own Folder: box.
- Exchange Online with OAuth authentication: the account, and its own Folder: box.
- Google Mail (IMAP4 + OAuth): the IMAP4 fields preset to
imap.gmail.com, port 993, and implicit SSL/TLS, with the server and port boxes unavailable, the Secure connection options hidden, and an OAuth sign-in in place of the password. A Google Mail job needs its client ID, client secret, and account.
The Folder: box on the Settings tab appears only for IMAP4 and Google
Mail. When you open a job whose folder is empty, the IMAP4, EWS, and Exchange
Online folder boxes are filled with Inbox. If you clear the IMAP4 and Google
Mail Folder: box after opening the job, the folder is saved empty.
Test Connection
Test Connection runs the Mail Connector with the values currently in the window, including unsaved changes. The button is available when the key fields of the server type are filled in:
- POP3 and IMAP4: the server, the port, and the user name.
- MAPI: a profile, or Use default profile.
- EWS: the user name, plus the URL or the Autodiscover address.
- Exchange Online and Google Mail: a signed-in account.
A successful test reports "Connection test completed successfully." A failed test reports "Connection to the mail server failed." with the error text in an extended view. When the list of MAPI profiles cannot be read, the window reports "Cannot receive a list of available e-mail profiles."
MAPI profile account
For MAPI, the Settings tab shows a Profile account group: Specify a Windows account to access the MAPI profile: with the options The Automation Server startup account and This account:, a user name box with Find..., and a password box. The profile must be created with a 64-bit edition of Microsoft Outlook on the Automation Server computer, for the profile account.
- A local Windows account is refused unless the database server and the Automation Server are the same computer: "The Automation Server cannot use a local account to run the Mail Connector. Please specify a domain account."
- When you change the account of a MAPI job, clicking OK runs a connection test first, and the job is not saved when the test fails. While the Automation Server is stopped, saving is abandoned with "Now you need to start the Automation Server and then click "Test Connection" to confirm that the Mail Connector can use the specified Profile Account."
- The Automation Server startup account must belong to the local Administrators group on the Automation Server computer, and the account you specify must have the Log on as a batch job user right. When a right is missing, the window reports "Make sure that the Automation Server startup account belongs to the local Administrators group on the Automation Server computer." or "Make sure that this Windows account has the "Log on as a batch job" user right."
Create the Outlook profile
NOTE: The Settings App's E-mail Notifications settings warn that MAPI support is being deprecated and will not be available in future versions, and recommend EWS for Exchange on-premises or a move of the mailbox to Exchange Online.
An Outlook profile holds the e-mail accounts, data files, and settings that Outlook uses. Only the Windows account that created a profile can use it, so create the profile while signed in as the profile account: the Automation Server startup account, or the account that you specify under This account:. Profiles created with a 32-bit edition of Outlook cannot be used. To create the profile:
- On the Automation Server computer, install a 64-bit edition of classic Outlook for Windows.
- Sign in to Windows on that computer as the profile account.
- Start Outlook. The first time Outlook starts for an account, it creates a profile named Outlook; add the Exchange mailbox that the job reads to it.
- If the account already has a profile and you want a separate one, open the
profile picker instead: hold Shift while starting Outlook, or run
Outlook.exe /profiles. Select Options, select New, type a name for the profile, select OK, and then add the Exchange mailbox. - Open the mailbox in Outlook to confirm that the profile works.
- In the Settings App, open the job. On the Settings tab, with Messaging Application Programming Interface (MAPI) selected, choose the profile name in Mail Profile, or select Use default profile to use the account's default Outlook profile.
- Under Specify a Windows account to access the MAPI profile:, choose the account that created the profile, and then click Test Connection.
When the job runs under the Automation Server startup account, the same profile can also send e-mail notifications over MAPI; see Outgoing E-mail Settings. For Microsoft's steps, see Create a profile in classic Outlook for Windows.
Grant the Log on as a batch job right
Grant the right in Windows to the account that you then specify under This account:. To grant it:
- Sign in as an administrator on the Automation Server computer.
- Open Local Security Policy.
- Under Local Policies, go to User Rights Assignment.
- Double-click Log on as a batch job.
- Click Add User or Group... and add the account.
- Click OK.
- Restart the Automation Server; see Start, stop, or restart the service.
For the user right itself, see Microsoft's Log on as a batch job.
Processing tab
The Operations group holds the tree of operations. Its New menu offers Create Object and Update Object, followed by "IF" Group, "ELSE" Group, and "ELSE IF" Group. The toolbar has Expand All, Collapse All, Move Up, and Move Down. An operation whose object class is not licensed cannot be opened or enabled again, and reports "Your license does not support this feature."
An operation opens in the Operation dialog:
- A create operation (Create New:) names a licensed object class and the create action to run for it.
- An update operation also identifies the record to update, by a GUID field
value or by an expression. The label of this row shows the chosen class, for
example Incident:. Its F(x) button opens the Build Expression
window, where the message fields are listed under E-mail Fields; choosing
one writes it into the expression as
%[EML <name>]%. - Enable operation turns one operation off without deleting it, independently of whether the job is enabled.
When you map the fields of a Mail Connector action, the message fields offered as sources are From, To, CC, BCC, Subject, Content (the message body), Sender, Sender Name, Sender E-mail, Priority, Auto-Generated, and Auto-Replied, plus every parsing rule and InactiveObjectRef. Sender is offered only when the target class is not Persons.
Under the tree:
- Create Persons: selects the action to run for senders that cannot be matched to a person. Press Delete or Backspace to clear it.
- Attach original e-mail message to object/activity attaches the original message to the record.
When you create a job, its tree is filled in for you. With the ITSM module licensed, it has update branches for Incident, Change Request, Problem, Work Order, Service Request, Approval Request, and Task, plus Purchase Order when ITAM is also licensed, and creates an Incident otherwise. With only ITAM licensed, it has branches for Purchase Order and Approval Request and no create fallback. Each branch uses the first enabled action of the right kind for its class, and a class with no such action gets no branch. The tree tests the ObjectRef field, branches on the class of the object it found, and updates that object.
Incoming e-mail handling
The Incoming e-mail handling group sets what happens to a message after it is processed:
- When an object is created or modified successfully: choose Mark the message as read or Mark the message as deleted, and select Purge the deleted messages at the end of session to purge.
- When a workflow item rejects the message: the check boxes Mark the message as read, selected for a new job, and Mark the message as deleted.
For a POP3 job, the read options are replaced by a fixed, unavailable Delete the message from the mailbox check box, and the rejected-message check box reads Delete the message from the mailbox.
Parsing rules
A parsing rule opens in the Edit Field dialog. For a rule of the logical type, the Starting after: and continues until: controls are replaced by one Check For: value that the extracted text is compared with. A rule's name must be unique and must not be the name of one of the built-in message fields; otherwise the dialog does not save it and shows an error.
MessageID Tag page
E-mail Processing > MessageID Tag reads "When receiving e-mail, the system searches for a special MessageID Tag in its Subject line to check if it is part of existing thread." It has:
- A MessageID Tag group with Prefix:, Suffix:, and an Example:
that shows the prefix,
T000001, and the suffix as you type. Both the prefix and the suffix are required. - A Position group, Insert the MessageID value automatically:, with At the beginning of email subject line, At the end of email subject line, and No automatic insertion, use only the "MessageID Tag" system macro. For macros, see Macros Reference.
Saving the page also rewrites the system parsing rule, ObjectRef, to search the subject for the new prefix and suffix. Any other change made to that rule by hand is discarded.