Skip to main content

Inbound email

An inbound email configuration connects a mailbox to the automator. The automator polls the mailbox and triggers a package for every new message, which makes email a trigger like any other. Typical uses are creating a request in Xurrent from an email, or processing reports that a system sends by email.

Inbound email configurations are configured in the Inbound email configurations tab.

Configuration​

General​

  • Enabled: only enabled configurations are polled.
    While a configuration is disabled, new messages stay in the mailbox and are picked up once it is enabled again.
  • Name: identifies the configuration.
    It is also part of the event name the package receives (see below).
  • Description: optional free text.
  • Protocol: how the automator reads the mailbox.
    IMAP works with any mail server that supports IMAP. Microsoft Graph reads a Microsoft 365 mailbox through the Microsoft Graph API.

Folders​

  • Inbox folder: the folder that is polled for new messages.
    Subfolders are not polled. For IMAP this is required and defaults to INBOX. For Microsoft Graph, leave it blank to use the standard Inbox folder, or enter the name of a top-level folder in the mailbox. The folder must already exist.
  • Archive folder: the folder that messages are moved to after they are processed.
    For IMAP this is required and defaults to ARCHIVE. The folder is always created as a subfolder of INBOX (also when a different inbox folder name is configured). For Microsoft Graph, leave it blank to use the standard Archive folder, or enter the name of a top-level folder.
    The automator creates the archive folder if it does not exist yet.

Folder names may only contain letters, numbers, hyphens and underscores.

Server (IMAP only)​

  • Host and Port: the address of the IMAP server, for example imap.example.com and 993.
  • Use TLS: connect over an encrypted (TLS) connection.
    Most servers require this, typically on port 993.
  • Reject unauthorized: verify the server's TLS certificate, and refuse to connect if it is invalid or self-signed.
    Only uncheck this for servers with a self-signed certificate that you trust.

Authentication​

  • Basic: authenticate with a Username and Password. Only available for IMAP.
  • Microsoft 365 Client ID + Client secret: authenticate as a Microsoft Entra app registration, using a client secret.
  • Microsoft 365 Client ID + Certificate key: authenticate as a Microsoft Entra app registration, using a certificate.

Both Microsoft 365 methods require:

  • Email address: the address of the mailbox to read.
  • Microsoft tenant ID: the ID of the Microsoft Entra tenant the app registration belongs to.
  • Client ID: the application (client) ID of the app registration.
  • Client secret, or Client certificate private key and Client certificate thumbprint: the credentials of the app registration.
    The private key is entered in PEM format.

With the Microsoft Graph protocol, the app registration needs the Mail.ReadWrite application permission, so the automator can read messages, mark them as read and move them to the archive folder.

Verifying the configuration​

Use Verify to check that the automator can connect to the mailbox. For IMAP, it connects, authenticates and opens the inbox folder. For Microsoft Graph, it also checks the Mail.ReadWrite permission and creates the archive folder if it does not exist yet.

Linking a mailbox to a package​

The configuration is linked to a package with an inbound email event. The package receives the message in the mail standard variable: sender, recipients, subject, body and attachments. The event name is email-in.<name>, where <name> is the name of the inbound email configuration.

A configuration can be linked to more than one package. Each linked package is then executed for every message.

How polling works​

Every minute, the automator polls each inbound email configuration that is enabled and linked to at least one enabled package. A configuration that is not linked to any enabled package is not polled, and its messages stay in the mailbox.

A poll picks up all unread messages in the inbox folder, oldest first. Messages that are already marked as read are ignored, so a message that someone opens in a mail client before the automator picks it up is not processed.

For each email message, the automator:

  1. Triggers every linked package with the message. The package executions are queued and run like any other execution.
  2. Marks the message as read and moves it to the archive folder.

Automatic replies, such as out-of-office messages, are archived as well, but the package executions are skipped. The automator recognizes them by the X-Autoreply, X-Autorespond or Auto-Submitted: auto-replied header.

When something goes wrong:

  • Mailbox unreachable, for example because of a network problem: the messages stay in the inbox folder and are picked up by a later poll.
  • Message cannot be processed: the message is retried by the next polls.
    After three failed attempts, it is moved to the archive folder without triggering any package.
  • Throttled by Microsoft Graph: polling pauses until Microsoft allows new requests.

In rare cases, for example when the connection drops after a package was triggered but before the message was archived, the same message might be processed twice. Packages that must not act twice on the same message can check whether they already handled it, for example by its message-id header in mail.headers.

See also​