Collect mailboxes

The Mailboxes module collects messages from mailboxes and hands each new message to a handler that processes it. Three handlers exist:

• TIMA (Service Desk module): each message creates a ticket whose requester is the sender; if the subject contains the number of an existing ticket (a reply to a notification, for instance), the message is added to that ticket;
• licensing (Licensing module): license files received as attachments are imported (see "Managing the instance licenses").
• servicecatalog (Service catalog module): each message creates a request on the service whose "Mailbox" trigger uses the mailbox; a reply becomes a comment (see "Automatic triggers").

The Inbound mailboxes screen is reserved for Administrators. It is in the Administration menu, under Connectors and automation.

Before you start: turn on collection

Collection is done by the MailInboxPolling scheduled task, every 5 minutes. It is disabled at installation: enable it in the Scheduler once your mailboxes and their handler are set up.

Read this before enabling it: a collected message is marked as read in the mailbox and is never collected a second time, even if it was not handed over (mailbox without a handler). Only unread messages are collected. A mailbox whose handler no longer exists (module removed) is not collected at all: its messages stay unread, and the mailbox's Last error says so.

Add a mailbox

New mailbox asks for:

• Name: free text, to recognise it in the list;
• Protocol: IMAP;
• for IMAP: Host, Port (993 by default), Security (Implicit (SSL/TLS), Explicit (STARTTLS) or None), the Folder to collect (INBOX by default), Username and Password;
• Message handler: chosen from the list of handlers available on the instance (TIMA, licensing…), or None — messages are then collected and logged, but handed to no one;
• Enabled: only enabled mailboxes are collected.

The password (or client secret) is stored as a secret value and is never displayed again. When editing, leave the field empty to keep the current value.

Microsoft Graph: collection through Graph is not available yet; the protocol is no longer offered when creating a mailbox. A mailbox already set to Graph stays editable but retrieves no messages (a warning on its page says so): switch it to IMAP.

Check a mailbox

Click a mailbox's name to open it. Test connection connects with the saved values (save your changes first) and shows "Connection successful." or the mail server's error message.

Below the buttons, Last polled gives the date of the last successful collection and Last error the message of the last failed one; the error disappears at the next successful collection.

For security reasons, the host cannot point to an internal network address (for example 10.x.x.x, 172.16 to 172.31.x.x, 192.168.x.x, 100.64 to 100.127.x.x, or the machine itself), a reserved address, or a local name (no dot, or ending in .local, .lan, .internal): the connection is refused with the message "Host refused". A name that does not resolve gives "Host not found". The mail server must be reachable through a public address.

Good to know

• Automatic replies (out-of-office, automatic acknowledgements) are collected but never handed to the handler.
• If the handler's module is not covered by the license, the mailbox is not collected: its messages stay unread and will be processed as soon as the license allows.
• The mailbox's Filters let you set messages aside before they are handed over (see "Filter incoming emails").
• Deleting a mailbox (the bin in the list, after confirmation) deletes it together with its collection history (processed and excluded messages), its filters and its stored password. To stop it while keeping all that, untick Enabled.

See also

• "Filter incoming emails": set messages aside before they are handed over.
• "Scheduling tasks": enable the MailInboxPolling task.