Inbound email connections enable email messages to be received by the Orchestration & Automation application, for example, messages from a
phishing report service. Playbook designers can configure Orchestration & Automation to consume email and automatically generate
incidents from the email, or add the email to existing cases.
You must know which protocol is used by your email service and the account to use. Also,
connections to mail servers with untrusted certificates fail by default. If you want to connect to
an email server with an untrusted certificate, you must have a copy of that certificate available
when prompted to upload it when the Test connection fails.
If your organization uses Exchange
email servers, it is recommended that you use the Exchange (EWS) protocol when configuring your
email connection in the following procedure. Otherwise, your system might have problems processing
emails that are larger than 25 MB.
You can configure one or more email connections from the Application Settings > Case
Management > Permissions and access > Organization tab. An email connection applies only
to the account in which you configure it. Any existing email connections are shown from Email
Connections on the Organization tab.
-
Click Administrator Settings > Organization.
- Select Inbound Email Connections and click Add
Connection +.
-
From the Mailbox section, enter a name, API name, and optionally a
description for the email connection.
-
From the Connection Details section, select the protocol that you want
to use.
-
If you choose Exchange, complete the following fields:
- In the Endpoint field, enter the URL to connect to the email server in
the following format:
https://<hostname>/<endpoint>
. For
example:https://outlook.office365.com/EWS/Exchange.asmx
- In the Email Address field, enter the email address of the target
mailbox. If you are using a shared mailbox, enter it using the format
primary_email\shared_email
, where the shared email section must be in the format
user@domain.com
, similar to the following examples:Example
1
primary_email@mail.com\shared_email@mail.com
where
primary_email@mail.com
has access to the shared mailbox.Example
2
myemailserver.com\info\sharedemail@myemailserver.com
- In the Password field, enter the password for the email address that you
entered in the previous step. If you are using a shared mailbox, enter the password for the primary
email account that is used to access the shared email, or for the shared email account if it has a
password set.
- Optionally, in the Source Folder field, specify the mailbox folder from
which unread email messages will be retrieved. If the source folder is not specified, messages are
retrieved from the Inbox folder.
- If using a proxy server, click Proxy to display the proxy connection
fields then enter the proxy information and authentication credentials:
- For Protocol, determine if the Orchestration & Automation is to connect to the proxy server over HTTP or
HTTPS. If the protocol is HTTPS, a proxy server certificate is required. If you are not using server
certificates from a trusted certificate authority, you must upload your own certificate when you
test the connection. If the specified protocol is HTTP, a server certificate is not required.
- In the Host Name field, enter the host name or IP address of the proxy
server.
- In the Port field, determine which proxy server port to use for the
inbound connection then enter the port number.
- If authentication is required to access the proxy server, enter the credentials in the
User name and Password fields. User name is required.
The requirement to provide a password depends on the associated user account.
- If you choose IMAP, complete the following fields:
- In the Host Name field, enter the host name or IP address of the email
server.
- In the Port field, enter the port number to connect to the email
server.
- In the Email Address field, enter the email address to connect to the
target mailbox.
- In the Password field, enter the password for the email address that you
entered in the previous step.
- Select an encryption method. The encryption method must be supported by the email service. Both
the SSL/TLS and STARTTLS encryption methods require
server certificates. If you are not using server certificates from a trusted certificate authority,
you can select the SSL/TLS or STARTTLS encryption
method and proceed to the following steps. After testing the connection, you can then upload your
own certificate. If you select None for no encryption method, you do not
require any certificate.
- If you choose the OAuth protocol, which is used for Office 365,
complete the following fields.
- In the Endpoint field, enter the URL to connect to the email server in
the format,
https://<hostname>/<endpoint>
, as shown in the following
example.https://outlook.office365.com/EWS/Exchange.asmx
- In the Application (Client) ID field, enter your Microsoft Application client ID.
- If your Microsoft Entra app is single-tenant, enter
the ID in the Directory (Tenant) ID field. If it is multi-tenant, leave this
field blank.
- You can choose between a client secret or certificate validation. Click Client
secret or Certificate, depending on whether you want to use a
secret or certificate for validation with the Microsoft
Entra application:
- In the Email Address field, enter the email address of the target
mailbox. If you are using a shared mailbox, enter it using the format
primary_email\shared_email
, where the shared email section must be in the format
user@domain.com
, similar to the following examples.Example
1.
primary_email@mail.com\shared_email@mail.com
where
primary_email@mail.com
has access to the shared mailbox.Example
2.
myemailserver.com\info\sharedemail@myemailserver.com
- You can also specify the mailbox folder in the Source Folder field, from
which unread email messages are retrieved. If the source folder is not specified, messages are
retrieved from the Inbox folder.
- In the Office 365 Access field, click Grant Access
then log in to your Office 365 account.
- If using a proxy server, click Proxy to display the proxy connection
fields then enter the proxy information and authentication credentials.
- For Protocol, determine whether Orchestration & Automation is to connect to the proxy server over HTTP or
HTTPS. If the protocol is HTTPS, a proxy server certificate is needed. If you are not using server
certificates from a trusted certificate authority, you must upload your own certificate when you
test the connection. If the specified protocol is HTTP, a server certificate is not needed.
- In the Host Name field, enter the hostname or IP address of the proxy
server.
- In the Port field, determine which proxy server port to use for the
inbound connection then enter the port number.
- If authentication is needed to access the proxy server, enter the credentials in the
User name and Password fields. You must enter a
username, but the requirement to provide a password depends on the associated user account.
If you are using the Azure platform, you need to enter the Orchestration & Automation URL with /email-oauth
appended
at the end when you register the application and enter the redirect URI.
- You must grant the "
EWS.AccessAsUser.All
" permission to your Microsoft Entra ID application.
- Click Test and Save Connection to validate that the connection
works. If the connection is not successful a message is displayed to indicate this. Correct any
problems and try again.
Note: If necessary, check the log file for information to help troubleshoot any errors.
The email connection is configured and the
Orchestration & Automation application can receive email messages. If you
want to subsequently delete the connection, select
Administrator Settings > Organization
> Inbound Email Connections. Click the delete icon for the connection that you want to
remove.
If you used the OAuth protocol, the Grant Access button becomes a
Switch Account button that allows you to change the Office 365 account used
for the inbound email connection.