Introduction

The MailIntegration program (ESI.Octopus.MailIntegrationApp.exe) allows you to receive emails in Octopus to:

• Create an incident
• Create a service request
• Create an event
• Update an existing request by adding an activity

For more information see the article MailIntegration - Create Incidents or Events from Emails 

Troubleshooting

It is possible that errors occur during its execution.

When email processing stops working, it is recommended that the following steps are followed to assist you in the analysis:

1- Event Management

When MailIntegration is able to run and an error occurs, an event with more details is generated.

• Blocked email (.EML file)
  • If in the event, there is an .EML file in the attachment tab, it is possible that this email blocks the execution of MailIntegration.
  • You have to remove this email from the inbox manually and observe if the other emails are processed correctly.
  • It is recommended to send this .EML file to Octopus support for analysis and to indicate on which event number it was generated.
• More frequent error messages

  • An event can display messages in the activity.

  • If the error is able to resolve itself automatically, such as a temporary unavailability on the mailbox, a message "Successful processing, closing the event" will be added as an activity and the event go to the "Processed" state automatically.

  • In cases where the event does not automatically resove, here are the more common error messages and probable causes:
    
     

    Messages	Probable Causes
    "Unable to connect to outlook.office365.com:995". A connection attempt failed because the connected party did not respond appropriately after a certain period of time or an established connection failed because the connecting host did not respond 52.66.88.133:995	The POP 3 server is not allowed for this IP address or the network blocks the connection to the POP3 server.
    "The BeginRead method cannot be called when another read operation is pending."	This may indicate that a concurrent or overlapping run has occurred.
    Access to the shared directory (YourServer\OctopusAttachments) is denied or the directory does not exist.	Access to the attachment directory of the Windows user running the MailIntegration task is missing. This path is set (by Team) in Tools ->Options.
    The Site name in the configuration file is invalid.	The Site entered in the XML file is not valid
    "An error occurred while authenticating against mail server." ERR Logon failure: unknown user name or bad password.	This indicates a problem authenticating to the mailbox (password, for example). 1. Access the outlook site (https://outlook.live.com/owa/) in private browsing 2. Authenticate with the user and same password indicated in the XML file. This information is populated in the XML file used by MailIntegration.
    One or more errors occurred. AADSTS700016: Application with identifiers 'nac256aa-21b5-478e-b666-3840d367d596' was not found in the directory 'MonDomain.com'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant. Trace ID: 8361626f-1205-4ba4-car0-f887fdcc9c43 Correlation ID: 1249af9c-83b8-422d-b34e-6dba83c0af35	This indicates that the clientID parameter of your XML file is not valid. It is recommended to use the MailIntegration configuration tool to test this parameter. See the MailIntegration Configuration Tool article for more details.
    One or more errors occurred. AADSTS90002: Tenant 'octopus-itsm.com' not found. Check to make sure you have the correct tenant ID and are signing into the correct cloud. Check with your subscription administrator, this may happen if there are no active subscriptions for the tenant. Trace ID: 9f1298fe-1a2c-4ar9-b955-033941425a98 Correlation ID: a6f8328f-be63-497b-8143-c0f6bfe3c40f	This indicates that the tenantID parameter of your XML file is not valid. It is recommended to use the MailIntegration configuration tool to test this parameter. See the MailIntegration Configuration Tool article for more details.
    The timeout period elapsed prior to completion of the operation or the server is not responding.	The POP 3 server is not allowed for this IP address or the network blocks the connection to the POP3 server. Validate that the port used by MailIntegration is open across all your network infrastructure and firewalls for the machine that is trying to access your mail server.
    The number of messages in the Inbox exceeds the maximum allowed (500).	It is suggested that you manually check the mailbox read by mailintegration to identify the reason for the number of emails to be processed, such as out of office emails or notifications causing a loop. If everything seems ok, you must move the messages exceeding the number of 500 to a temporary folder and after processing by mailintegration, move them back in the inbox to finalize their processing.
    POP3 server did not respond with a +OK response to the STAT command.	This error occurs randomly and usually resolves on its own. However, if the error persists or comes up often, it means a problem with the email account. We've frequently encountered this issue with mailboxes hosted in Microsoft Exchange Online (Office 365). To diagnose this error, you can enable POP3 logs in MailIntegration. It is important to correlate these errors with the connection logs in the system where your mailbox is hosted. If you're using Microsoft Exchange Online (Office 365), be sure to also check the login logs for the enterprise application used by MailIntegration.

2- .log File

If the information in the event is not clear enough or if an event has not been created, check the .LOG file to find the error message.

This file is normally created in the Octopus directory where MainIntegration is executed, or if not, in the path specified in the MailIntegration command line, parameter /LogFilePath.

By default, the fils is named MailIntegration_YYYYMMDD_HHMMSS.log and will be located in the Octopus directory.

More frequent error messages in the LOG file:

3 - No message in the .log file

If there is no recent activity in the .LOG file, it is possible that MailIntegration is not able to be executed.

In this case, you must test the integrity of the Octopus client by running the file ESI.Octopus.WinUI.exe in the same directory as the MailIntegration program.

For more details, see the article Octopus System Requirements.

In this case, when running ESI.Octopus.WinUI.exe, the following message is displayed and the Octopus client does not start at all, the MailIntegration application mus be reinstalled, because the installation is corrupted.

4 - Browser Cookies

Delete cookies and browsing history in the Windows profile that runs the MailIntegration task.

The Octopus application uses web components, so this is the reason why it is related to the cookies

5 - Permissions

For MailIntegration to be able to process e-mails correctly, you need to give permissions and the role: Batch to the System account that processes MailIntegration, ADSI, etc. For mor details, see the detailed article. 

6 - Others

You can contact Octopus Support if the client starts and there is no other information available.

7 - Enabling the POP3 Transaction Log

In rare cases, it may be useful to enable an advanced diagnostic tool in MailIntegration. This logs all POP3 transactions that occur during the dialog between MailIntegration and the remote server.

To enable these traces:

1. Identify the XML file used by MailIntegration that is having the problem
2. Open this file
3. Locate the closing tag of the MailIntegration configuration (</mailIntegration>)
   • This tag is normally located on the last line of the file
4. BEFORE this line, add the following: <protocolLoggerFileName>[FullLogFilePath]</protocolLoggerFileName>
   • Replace [FullLogFilePath] with a path where you want logging to be performed
   • This path must be a file name. For example: C:\TaskManager\MailIntegration\Logs\POP3.log
5. Save the XML file
6. Future MailIntegration runs will use this file to log POP3 transactions.