MailIntegration - Create Incidents or Events from Emails


Table of contents

Related articles


MailIntegration (ESI.Octopus.MailIntegrationApp.exe) is a program used in Octopus to create new requests (incidents, service requests or events) or update the activities of a requests received via email. The program needs to be automated using the Windows Task Manager.

If you want to create incidents from a surveillance system, System Center Operations Manager 2007 for example, please consult the Create events from emails section. 

What you need to know:
To use MailIntegration, you need a dedicated email account and you need to make sure that the POP3 protocol is enabled on your email server.

How MailIntegration Works

When MailIntegration is started, it will read the mailbox to see if it contains any new messages. If it does, the program will validate if the email is a new incident, an event or meant to update an activity in an existing request. 

The method used by Octopus to "recognize" an email is the following. Octopus reads the email subject and if the request number is found in a specific format, it will update the request, otherwise it will create a new incident/event.

In the image bellow, the first part represents the format that Octopus looks for to update a request:

  • The communication type in between square brackets.
  • Sometimes followed by the name of the DB or the team name.
  • The request number.

In the case where it is a new email, MailIntegration will create a new incident or event in Octopus. The email subject will be the incident/event subject and the email body will be placed in the detailed description. For an incident the sender will be tagged at the requester/user. If the email of the sender is not recognized by Octopus, the incident requester/user will be the system user previously defined (Fallback user). 

If the email concerns an existing request, an activity will be added to the request containing the name of the sender, as well as the date and time of the activity in Octopus.

Email processed by MailIntegration will then be deleted. This is the standard behavior for the POP3 protocol. To keep a copy of received mails, you will have to configure your system in one of the following way, depending on the Mailing system used. We invite you to contact your mail administrator to decide which is right for you.

  • Use a distribution list that delivers email in a mailbox meant for MailIntegration and a mailbox meant for archives.
  • Configure a server-side mail delivery rule that will also send email received in a mailbox meant for archives.
  • Configure a server-side mail copy rule that will also copy email received in a folder meant for archives.



Email Account

Have an email account that is dedicated to Octopus. To configure MailIntegration, you need the following information:

  • The complete address of the account.
  • The name of the user of the account.
  • The account password.
  • The email server name.

POP3 Protocol

The only supported protocols for the MailIntegration program are POP3 and secure mode POP3 (SSL). The protocol to use needs to be activated on the email server that will be used.

If you want to use POP3 in secure mode (SSL), you have to make sure the machine executing MailIntegration recognizes the authenticity of the certificate used, either by using a trusted certificate authority, or by locally installing the server's self-signed certificate.

Test the POP3 Protocol

MailIntegration will not function if the protocol test does not work, you will find the information to do this test in the MailIntegration - Testing the POP3 connection page. 

System User

A system user should be designated to associate with incidents when the sender's email is not recognized by Octopus.

This user could also be configured to run the Windows task. For more information on the subject, see the Octopus System Account article.

Configure the email address used by Octopus

Before using MailIntegration, you need to have configured the dedicated email address that the system will use to communicate with users. 

Go to Tools > Options > Section 1 - Email Options > Email address used by Octopus.

Add the address of the dedicated email account and check the Always use this address when sending emails box. 

Attachment Directory

Before using MailIntegration, the network path for the Attachments needs to be configured in Octopus.

Go to Tools > Options > Section 3 - Important general options > Network directory containing the attached files.

In case of a problem an event is automatically created

It is important to note that in case of issues with MailIntegration, Octopus will create an event with instructions on how to resolve it. For this reason, before activating MailIntegration, we recommend to ensure members of your Service Desk have subscribed to the New Event notification. 

  • (File menu > My notification preferences... > New Event).
  • The permission Access the Event Management module is also required.

Octopus displays a specific content when an error with an email message is encountered.

When a problem is detected, the event management shows a new entry that contains the original message blocking the application.



The message can be seen in the "Attached Files" tab.


Attached Files

MailIntegration will do the same when an already existing event gets a new activity.

In case of an infrastructure outage detection, Octopus also creates an event but this time, it displays a message that contains the issue's source.


Infrastructure issue

The configuration file will be attached(without passwords, if required) in an .XML format.


Infrastructure issue - XML file

Octopus will continue to add additional activities as long as the issue is still occurring.


Additional activities

Furthermore, once the MailIntegration issue gets resolved, Octopus then proceeds to automatically mark the event as processed.


Automatic closure

Using the MailIntegration Program

MailIntegration is a command line type program (DOS). It is designed this way to be easy to automate (the Automate email updates in Octopus section describes how to automate the execution of MailIntegration). 

  • The complete name of the program is: ESI.Octopus.MailIntegrationApp.exe
  • It is located in the local Octopus folder (C:\Program Files\Octopus) or in (\%homepath%\AppData\Local\Octopus)
  • Example of the folders where Octopus can be found:
    • For Windows 7: C:\Users\slevesque\AppData\Local\Octopus
    • For Windows XP: C:\Documents and Settings\Slevesque\Local Settings\Application Data\Octopus

What you need to know:

Each time the program is run a .LOG file is created in this format; ToolName_YYYYMMDD_HHMMSS.log

  • For example MailIntegrationApp_20190618_105242.log.

Use this file to see the results of the command execution and errors if there are any.

Also see the Octopus Tools | Maintenance of log files article about the importance of the log file management. 


There are 6 available parameters to execute MailIntegration, of which 4 are mandatory:

Mandatory Parameters

  • /Login
    • Octopus user name.
    • This account will be used to create the incidents and will be visible in the history tab. It is better to use a dedicated account for this program. (Example: Mail Octopus).
  • /Password
    • Octopus password.
  • /Team

  • /ConfigFilePath
    • Path to the configuration file.

The next section explains how to prepare the configuration file.

Optional Parameters

  • /LogFilePath
    • To replace the path to the log file. By default, the file is named MailIntegration_AAAAMMJJ_HHMMSS.log and is located in the Octopus folder. If you move the file to another folder, the folder needs to exist (the system cannot create the folder). Furthermore, the path needs to contain the file name.
      • Example:/LogFilePath:C:\LogFiles\MAILINTEGRATION.log
  • /Debug
    • In cases where we need to troubleshoot an issue, our Service Center may ask to have this parameter added to create a RAW message for each message received and help to investigate the problem. Note that if you activate this parameter the Octopus folder may get large amount of RawMessage.txt files and will need to be cleaned up regularly.
  • /PurgeLogs

Operations Log File

Files generated by the execution of the MailIntegration program:

  • MailIntegrationApp_YYYYMMDD_HHMMSS.log
    • Operation log file generated each time the program is executed
  • RawMessage.txt
    • Content of the email in raw text in case of problem or at the request of the Octopus Service Center by adding the /DEBUG parameter 

The files are created in the same folder at the executable "ESI.Octopus.MailIntegrationApp.exe". Furthermore, these files can be requested to troubleshoot a MailIntegration issue.

Configuration File (XML)

The configuration file is a text file containing the information on the mail server, the username and password of the mailbox to use, as well as other parameters required by the program. This file uses the .XML format. The following section explains the 2 formats available for the .XML file, one for POP3 and the other for SSL. 


Be careful not to change the format of the information contained in the file. As any "/" or "<" missing in the structure can render the file unusable. Make sure that the specified values are valid. Do not leave any empty spaces before or after the values. 

In case of errors with the configuration, the program will stop working and an Event will be created in Octopus with details on the problem.

To view the information contained in the file, you can use a software like Internet Explorer. And to edit, we recommend Notepad or Notepad++.
Accents are not supported in the XML file. You need to replace the accents with the corresponding HTML code Entity


 must be replaced by

To find the HTML Entity accent correspondence, consult the following Correspondence Table.

Incident creation using a XML POP3 file

Open the following file in Notepad:

<?xml version="1.0" encoding="utf-8" ?> 
  <MessageProcessorTypeName>ESI.Octopus.MailIntegration.EndUserIncidentMailMessageProcessor, ESI.Octopus.MailIntegration</MessageProcessorTypeName> 
    <GatewayTypeName>ESI.Octopus.MailIntegration.SidePopMailboxGateway, ESI.Octopus.MailIntegration</GatewayTypeName>

The highlighted sections need to be configured. These tags are explained in the following section.

Explanation of the Tags

  • <ServerName>SERVER</ServerName>:
    • Name of email server.
      • Replace SERVER with the name of the email server
  • <UserName>MAILBOX</UserName>:
    • Username of the mailbox account.
      • Replace MAILBOX with the user account name used to authenticate. Normally this does not include the domain part of the public email address. For example, you would indicate “newincident” here, not “”.
  • <Password>PASSWORD-CLEAR-TEXT</Password>:
    • Mailbox account password
      • Replace PASSWORD-CLEAR-TEXT with the password of the mailbox account.
  • <IncidentFallbackUserLogon>FALLBACK-USER</IncidentFallbackUserLogon>:
    • Generic username to be used in cases where the email address of the sender is not recognized by Octopus. 
      • Replace FALLBACK-USER by the windows username of an existing Octopus user. This must be the same value as recorded in the Windows Username field of the user's file in Octopus. If an email is received form an address that is not recognized by Octopus, the system will use the fallback user indicated here as the incident’s “Requestor” and “User”.
  • <IncidentFallbackSiteName>FALLBACK-SITE<IncidentFallbackSiteName>:
    • This tag will be mandatory only when the site is mandatory in Octopus. (Tools menu > Options > section 3 - Important general options > Visible and required fields)
      • Replace FALLBACK-SITE with the name of a site that exists in Octopus. When the program runs it tries find the Octopus user based on the email address of the sender. If that sender is not recognized or if the user has no site, the system will use the site indicated here. If the site is not mandatory in the options, this tag can be removed.
  • <IncidentSource>INCIDENT_SOURCE</IncidentSource>:
    • Indicates the incident creation source
      • Leave Email in this tag to indicate that the incident was created from an email.
      • For another source, it needs to previously have been configured in the reference data management of Octopus.

  • <IncidentPriority>PRIORITY</IncidentPriority>
    • ​This tag is not mandatory. It allows to add a default priority to incidents/SRs created from MailIntegration. Note that this tag will take precedence over the default priority of the options and those of SR types.
      • Replace PRIORITY with the name of an existing priority in Octopus.
      • If according to the best practices, the priority is evaluated at the reception of the request, the tag will not need to be changed, remove this line from the XML file.
  • <IncidentGroup>ASSIGNED_GROUP</IncidentGroup>:
    • This tag is not mandatory. It indicates the name of group that differs from the service center during the incident creation. This option is usually used if mailintegration is configured for more then one mailbox
      • Replace ASSIGNED_GROUP by the name of the group that would be assigned to requests from this mailbox. To assign requests to the service center by default, remove this line from the XML file.
  • <IgnoredAttachments></IgnoredAttachments>
    • This tag is not mandatory. It is used to ignored some attached files. For example: a logo.
      • Indicate a comma-separated list of files to be ignored, including the extension.
  • <CreateNewRequests>True</CreateNewRequests>
    • This tag will determine if new incidents can be created from an email message that is not linked to an active request. 
    • If the new request creation is deactivated, the system will respond to the user with an email message based on a template that can be found in Tools > Options > Other messages section  -  Automatic reply for denied request creation by MailIntegration.
  • <IncludeRawMessageAsAttachment>True</IncludeRawMessageAsAttachment>
    • This tag controls if a copy of the email message in EML format will be attached to the created incident.
  • <traceMessageInfo>False</traceMessageInfo>

    • This tag is not mandatory. It allows adding more information to the log file:

      • MessageID

      • From

      • To

      • Subject

      • Date

  • ​​<sleepTimeAfterDeletion>0</sleepTimeAfterDeletion>

    • This tag is not mandatory. It allows for a delay before retrieving an email after deleting the previous one.

    • This tag must contain a number representing the delay in milliseconds.

    • If you are experiencing issues with requests or activities being recorded twice, we recommend adjusting this setting upward by 5000 milliseconds increment.

Once the tags have been configured with the proper information, save the file to the Octopus folder with the .xml extension. For example "Email-Integration.xml"

Using a POP3 SSL

Open the following file in Notepad:

<?xml version="1.0" encoding="utf-8" ?>
  <messageProcessorTypeName>ESI.Octopus.MailIntegration.EndUserIncidentMailMessageProcessor, ESI.Octopus.MailIntegration</messageProcessorTypeName> 
    <gatewayTypeName>ESI.Octopus.MailIntegration.SidePopMailboxGateway, ESI.Octopus.MailIntegration</gatewayTypeName>

The sections in yellow are the additional ones used with SSL. These new tags are explained in the following section.


Explanation of the Additional Tags

Refer to the previous section for the description of the tags common to both files.

  • <serverName>SERVER</serverName>
    • When SSL mode is enabled, make sure you enter a server name that matches the certificate named used to secure communications.
  • <useSsl>true</useSsl>:
    • When set to "TRUE", the system will use the SSL protocol
  • <port>995</port>:
    • Indicates the port to use.

Create events from emails

Copy the following file to your text editor:

<?xml version="1.0" encoding="utf-8" ?>
  <messageProcessorTypeName>ESI.Octopus.MailIntegration.EventMailMessageProcessor, ESI.Octopus.MailIntegration</messageProcessorTypeName>
    <gatewayTypeName>ESI.Octopus.MailIntegration.SidePopMailboxGateway, ESI.Octopus.MailIntegration</gatewayTypeName>

The sections in yellow are the ones that need to be configured. These tags are explained in the next section. Then save the file in the Octopus folder with the ".xml" extention file. For example "event-email-integration.xml"

Explanation of the Tags

  • <ServerName>SERVER</ServerName>:
    • Name of email server.
      • Replace SERVER with the name of the email server
      • With Office 365, must be

  • <UserName>MAILBOX</UserName>:
    • Username of the mailbox account.
      • Replace MAILBOX with the user account name used to authenticate. Normally this does not include the domain part of the public email address. For example, you would indicate “newincident” here, not “”.
  • <Password>PASSWORD-CLEAR-TEXT</Password>:
    • Mailbox account password
      • Replace PASSWORD-CLEAR-TEXT with the password of the mailbox account.
  •  <Group>GROUP</Group>
    • This tag is used to designate the group in charge of events
      • Replace GROUP with the name of the group assigned to events
  • <Assignee>ASSIGNEE</Assignee>
    • This tag allows to assign events directly to an Octopus user in the case where only one person takes care of events
      • Replace ASSIGNEE with the Windows username of the technician assigned to events. This tag can be left empty (<assignee></assignee>)

Execute MailIntegration from a Command Line

NOTE: Before running tests with MailIntegrationApp, it is recommended to test the POP3 connection to the server using the following procedure: Testing the POP3 connection

To run the MailIntegration executable file, open a DOS prompt and go to the Octopus folder. Then use the following command line:

Before 3.8

ESI.Octopus.MailIntegrationApp.exe /login:system /password:octo /ConfigFilePath:C:\Program Files\Octopus\email-integration.xml

After 3.8

ESI.Octopus.MailIntegrationApp.exe /login:system /password:octo /team:1 /ConfigFilePath:C:\Program Files\Octopus\email-integration.xml

To test MailIntegration for the first time, follow these steps:

  1. Send an email to the Octopus dedicated mailbox
  2. Open a DOS prompt
  3. Go to the Octopus folder
  4. Enter the following command along with the proper values for the 3 parameters and do ENTER:
    ESI.Octopus.MailIntegrationApp.exe /Login:OctopusUserName /Password:OctopusPassword /ConfigFilePath:(path to XML file)
    ESI.Octopus.MailIntegrationApp.exe /Login:OctopusUserName /Password:OctopusPassword /team:TeamNumber /ConfigFilePath:(path to XML file)

    The program will work for a few seconds and finish.

  5. Open Octopus and check the incidents listed under "New" to find the one just created.

Automate Email Updates in Octopus

MailIntegration only runs once at a time. Therefore, the execution of MailIntegration needs to be automated to check the mailbox regularly. 
Refer to the Windows Scheduled Tasks article to automate the reception and updates of email.

Use MailIntegration with Office 365

The following points are required for MailIntegration to work with Office 365:

  • Use MailIntegration with the SSL Mode and Port 995 configured in the XML file.
  • The mailbox must have an Office license.
  • Configure as the server name in the MailIntegration XML file.
  • Adjust firewall rules so the automation server (running MailIntegration) is able to establish outbound connections to port 995 of the following machines:

    • (as per Microsoft's documentation)



Help us improve our articles

Help us improve our articles