Establishing the Connection from the Email Agent to the IMAP Mail Server

{"URL":["/*.*/awa/pa_view_pa_view_CONN_email"],"heroDescriptionIdentifier":"ice_hero_CONN_email","customCards":[{"id":"ice_specific_CONN_email","title":"Defining the Connection Parameters","type":"customize","url":"https://docs.automic.com/documentation/webhelp/english/ALL/components/IG_EMAIL/*.*/Agent%20Guide/Content/Email/Email_EstablishConnection.htm","languages":["en-us"]},{"id":"ice_related_information_CONN_email","title":"Related Information","type":"customize","url":"https://docs.automic.com/documentation/webhelp/english/ALL/components/IG_EMAIL/*.*/Agent%20Guide/Content/Email/Email_EstablishConnection.htm","languages":["en-us"]}]}

The communication between the Email Agent and the target system is established by Connection objects. The Email Connection object contains the parameters (target system endpoint, credentials and so on) required to authenticate on and connect to the IMAP Mail Server.

Important!

Ensure you enable the Requires SSL checkbox in the IMAP server settings for the Listening Port and restart your computer.

As an administrator user, you create the Email Connection object that provides the login data required to establish the connection to the IMAP mail server. As a developer or object designer, you assign the respective Email Connection object to the Automic Automation Email Jobs to create and process the email (move, delete, or download them) without leaving Automic Automation. This page explains how to configure the Email Connection object.

Note:

By using more than one Connection object, multiple mailboxes are accessible. Combining multiple mail server addresses within one Connection object is not possible.

This page includes the following:

Adding an EmailConnection Object

In the Automic Web Interface, go to the Process Assembly perspective. It opens to the Explorer view which contains the list of jobs that are available to you in your system.
You have two options:
- Right-click anywhere on the list and select Add > Add Object.
- Click the Add Object button on the toolbar.
On the Add Object dialog, start typing the name of the relevant integration in the Search field.
Select the corresponding Connection object and click Add. The Object Name dialog is displayed.
Enter a descriptive Name.
Optionally, enter a short and descriptive Title that helps you recognize the purpose of the object.
Click OK. A new page opens where you can start with the object definitions.

Email Connection Page

The Mail Connection page consists of the Connection section where you define the parameters relevant for the connection to the IMAP mail server:

Email-Specific Connection Section

In this section, you define the parameters relevant for the connection to the IMAP Mail server environment.

Mail Server

The mail server address to which you want to connect, for example:

imap.gmail.com or outlook.office365.com
Authentication Type

The authentication types available for your connection are:
- PLAIN (default)
  
  Plain authentication mechanism.
  - User Name
    
    Email address of the user.
    
    Example
    
    test@gmail.com
  - Mail Account Password
    
    The password to access the mail account.
  - Properties
- OAUTH2
  
  Select OAUTH2 to set up either Google OAuth2 or Microsoft OAuth2.
  - Google OAuth2
    
    To use the Google OAuth2 authentication method, you need to generate client credentials such as the Client Id, Client Secret and token URI. You can generate them using the following URL: https://developers.google.com/identity/protocols/OAuth2#basicsteps.
    
    Basically, you will be required to go through the following steps:
    1. Create the Project.
    2. Enable API and Services -> Gmail API
    3. Click Create credentials > OAuth client ID by selecting the Web application type.
    4. Add Authorized redirect URIs. For example:
      
      http://localhost
    5. Go to APIs & Services and click the OAuth consent screen and add the "test user" under "Test Users".
    Download the JSON file for the created project. The JSON file will look as follows: it will have a Client Id, Client Secret, and a token URI, which you can use in the Email Connection object:
    
    "web":
    {
    "client_id":"<Client Id>",
    "project_id":"aaemailintegration",
    "auth_uri":"https://accounts.google.com/o/oauth2/auth",
    "token_uri":"https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs",
    "client_secret":"<Client Secret>",
    "redirect_uris":["http://localhost"]
    }
    }
    - Set up Google OAuth2 using Refresh Token
      
      First, you need to generate the code, followed by generating a refresh token.
      
      Code Generation
      
      Open the browser and paste the following URL after adapting it as per your environment ( {clientid}, {redirect_uri} ):
      
      https://accounts.google.com/o/oauth2/auth?access_type=offline&prompt=consent&response_type=code&client_id=%7bclientid%7d&state=https://mail.google.com&scope=https://mail.google.com&redirect_uri={redirect_uri}
      
      You will be required to log in to your email account and request the necessary permissions. This email account should be the same as the one in which you want to read the emails.
      
      Once the authentication is successful, you will be redirected to the following URL(As specified in the redirect URIs):
      
      http://localhost/?state=https://mail.google.com&code={code}&scope=https://mail.google.com/
      
      Extract the {code} and note it somewhere.
      
      Note:
      {Code} may include some encoded characters like "%2F". Replace it with a slash character (/).
      
      Refresh Token Generation
      
      Run the following command (requires CURL or a similar utility) where you replace {clientsecret}, {clientid}, {code}, {tokenuri}, and {redirect_uri};
      
      curl -XPOST -d "client_secret={clientsecret}&grant_type=authorization_code&code={code}&client_id={clientid}&redirect_uri={redirect_uri}" "{tokenuri}"
      
      Note:
      The code is valid only once. It will expire immediately once you use it. However, you can generate the code again, as shown above.
      
      The above curl command will provide the following output:
      
      {
      "access_token": "<your access token>",
      "expires_in": 3599,
      "refresh_token": "<your refresh token>",
      "scope": "https://mail.google.com/",
      "token_type": "Bearer"
      }
      
      Make a note of the refresh token as you will need it while defining Email Connection object.
      
      Note:
      Refresh tokens are long-lasting tokens.
      
      Define the following fields in the Email Connection section:
      - User Name
        
        Specify the user name, mail address or mailbox from where you want to read the emails.
        
        Example
        
        sampletest241@gmail.com
      - Token Request URL
        
        https://oauth2.googleapis.com/token. This should be the same as the token URI.
      - Client Id
        
        Specify the Client Id.
      - Client Secret
        
        Specify the Client Secret.
      - Refresh Token
        
        Specify the refresh token.
      - Generic Body
        
        &grant_type=refresh_token
        
        You may add more by appending &<key>=<value>
      - Properties
        
        (Optional) Specify properties in the format <key1>=<value1>. For multiple properties use the semicolon character (;) as a separator, for example <key1>=<value1>;<key2>=<value2>
        
        Tip:
        You might need to specify some properties specific to your environment or for debugging purposes. For example mail.imaps.auth.xoauth2.disable=false;mail.imaps.auth.plain.disable=true. For a list of available properties (prefix mail.imap), refer to https://javaee.github.io/javamail/docs/api/com/sun/mail/imap/package-summary.html. For debugging, use mail.debug=true
  - Microsoft OAuth2
    
    To use the OAuth2 authentication method for Exchange application, you need to set up an application under "App Registrations" in the Microsoft Entra ID (formerly known as the Azure Active Directory (AAD). Do so following the steps described here: https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app. After that, you should have a Client Id and a Client Secret that you can use in the Email Connection object.
    
    There are three ways to set up the Email Connection object:
    - (Recommended) Set up Microsoft OAuth2 using Client Credentials
      
      This setup requires the IMAP.AccessAsApp permission is granted to the AAD Application you have already set up.
    - Set up Microsoft OAuth2 using Refresh Token
      
      This setup requires the following permissions granted to the AAD Application you have already set up. These permissions belong to Microsoft Graph:
    - Set up Microsoft OAuth2 using Password
      
      Note:
      This mechanism might not work where Multi-factor Authentication (MFA) is enabled for mail accounts.
      
      This setup requires the following permissions granted to the AAD Application that you have already set up. These permissions belong to Microsoft Graph:
      - IMAP.AccessAsUser.All
      - offline_access
      Define the following fields in the Email Connection object:
      - User Name
        
        Specify the user name, mail address or mailbox from where you want to read the emails.
        
        Example
        
        IntegrationFactory@1rsrvm.onmicrosoft.com
      - Mail Account Password
        
        Specify the password.
      - Token Request URL
        
        https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token. Ensure you replace {tenant} with a valid value as per your environment.
      - Client Id
        
        Specify the Client Id.
      - Client Secret
        
        Specify Client Secret.
      - Generic Body
        
        &grant_type=password&scope=https://outlook.office.com/.default
        
        You may add more values by appending &<key>=<value> or you can specify &grant_type=password&scope=https://outlook.office365.com/.default
      - Properties
        
        (Optional) Specify properties in the format <key1>=<value1>. For multiple properties use the semicolon character (;) as a separator, for example <key1>=<value1>;<key2>=<value2
        
        Tip:
        You might need to specify some properties specific to your environment or for debugging purposes. For example mail.imaps.auth.xoauth2.disable=false;mail.imaps.auth.plain.disable=true. For a list of available properties (prefix mail.imap), refer to https://javaee.github.io/javamail/docs/api/com/sun/mail/imap/package-summary.html. For debugging, use mail.debug=true
Secure IMAP

(Optional) Enable this field to use secured IMAP.

Common Definition Pages

In addition to the Agent-specific connection parameters, you can also specify optional properties. You do so on the following definition pages:

Once the Connection object is configured, developers and object designers can select it when defining the Mail Jobs.