Page tree

Email Setup with Microsoft OAuth 2.0

Agiloft can be configured to access your Exchange Online mailboxes via SMTP and IMAP connections with OAuth 2.0 for authentication. For the best security and long-term Microsoft support, Microsoft recommends that you use Microsoft Graph protocol instead. For instructions on using Graph, see Email Setup with Microsoft Graph.

Since most systems benefit from setting up an outbound account and at least one inbound account, this article guides you through the steps required to set up both outbound and inbound email.

Notes

  • This setup replaces the outbound mail server that is configured by default. We strongly recommend replacing the default configuration with your email service so messages from Agiloft are sent from your organization's domain. Otherwise, email sent from the system is likely to be blocked or seen as spam by your email server.
  • Though some email-related fields, variables, and properties in Agiloft include "smtp" in the name, the instructions below configure Agiloft to authenticate via Microsoft's modern authorization with OAuth 2.0 protocol. Agiloft does not use SMTP authentication.

Prerequisites

Before setting up email in Agiloft, review the following list of requirements and recommendations:

  • Microsoft's modern authentication with OAuth 2.0 still requires client SMTP authentication to be enabled for the tenant in which Agiloft is registered. In addition, Authenticated SMTP must be enabled for any outbound email accounts. See Microsoft's documentation for more information. For newer Entra and Microsoft 365 environments where SMTP authentication is disabled by default or if your security policies disallow SMTP authentication, Microsoft recommends that you use Graph protocol instead. See Email Setup with Microsoft Graph for instructions.
  • Agiloft supports Microsoft's client credentials flow or device code flow for authorization. Other token grant flows are not supported. Client credentials flow requires more upfront configuration in Entra and Exchange Online than device code flow, but it's simpler to set up in Agiloft. Device code flow is simpler to set up in Entra but requires additional authentication steps when configuring Agiloft. This page includes separate instructions for each type of flow so you can preview the steps and choose the appropriate method for your organization.
  • To complete the setup, you need admin access to the Entra admin center with permission to configure new applications. If you use client credentials flow, you also need admin access to Exchange Online with permission to configure service principals and permissions.
  • We recommend you create at least one separate email account exclusively for use with Agiloft. 
    • At a minimum, you need one account to use as the default outbound address.
    • If you're setting up inbound email, you need an account to use as the inbound address. You can use the same mailbox for both outbound and inbound email. Many systems create an address like table_name@yourdomain.com, such as contracts@yourdomain.com for the Contracts table, and use this address for both inbound and outbound email.
    • If you plan to set up additional inbound or outbound accounts, you also need email accounts for those addresses. The setup of multiple outbound accounts is rarely implemented for Agiloft systems. For information on using them, see Add Optional Outbound Accounts for Tables. Instructions for connecting multiple inbound accounts are included in this article.

      Though you can use the same email address for the default outbound account and one inbound account, you can't use the same address for multiple inbound accounts. To minimize issues, prevent collisions, and ensure incoming messages are routed correctly, each table must have a distinct inbox.

    • If you use device code flow, you need the credentials for these accounts to complete the authorization with Microsoft after setting up email in Agiloft.
  • We don't recommend using shared mailboxes. Since shared mailboxes don't have credentials and can't be authenticated with OAuth, you can't connect Agiloft directly to them. You can configure Agiloft to access a shared mailbox through a licensed user account with permission to send as the shared mailbox. However, if that user is deactivated in the future, Agiloft loses access to the shared mailbox and email stops working. The setup is more straightforward and reliable if you configure regular licensed accounts as Agiloft's inbound and outbound mailboxes.

When you're ready to get started, proceed with registering Agiloft in Entra.

Register Agiloft in Entra

Before setting up email in Agiloft, follow the steps below to register Agiloft as an app in Entra ID.

If the options you see in the admin center differ from those described here, refer to Microsoft's app registration instructions to complete the task.
  1. Sign in to the Entra admin center as an administrator with permission to configure new applications.
  2. If your account has access to multiple tenants, select your account in the upper right corner and set your session to the appropriate tenant. For more information about tenants, see Microsoft's tenant documentation.
  3. Go to Identity > Applications > App registrations and select New registration.
  4. Enter a name for the registration. For example, you might name your registration "Agiloft OAuth Email."
  5. Select the appropriate option for which accounts can use the application. This choice depends on the IT security policy for your organization.
  6. Leave the Redirect URI empty.
  7. Click Register. The admin center automatically directs you to the overview page for the new application.
  8. Copy the Application (client) ID and Directory (tenant) ID from the overview page. Store these in a note so you can refer to them later.
  9. If you plan to use client credentials flow, you must also generate a client secret:
    1. Click Certificates & secrets in the sidebar.
    2. On the Client secrets tab, click New client secret.
    3. Enter a description, select the longest available expiration date, and then click Add. When the secret does expire, you'll need to repeat this step to generate a new secret and then update your email configuration in Agiloft with the new value. See Replacing an Expired Client Secret for instructions.
    4. Copy the secret value and store it in a note so you can refer to it later. You won't be able to access it after this point.

Now that Agiloft is registered, the next step is to configure the app according to the token grant flow you want to use.

Configure the App for Client Credentials Flow

Follow the steps below to configure the app for use with client credentials flow. The steps guide you through adding the appropriate Microsoft Graph and Office 365 Exchange Online API permissions and granting your email accounts access to the application.

  1. In the Entra admin center, click API Permissions in the sidebar.
  2. First, delegate Microsoft Graph API permissions:
    1. Click Add a permission and choose Microsoft Graph.
    2. Click Delegated permissions and select all of the OpenId permissions:
      • email
      • openid
      • offline_access
      • profile
    3. If you plan to enable inbound email, search and select IMAP.AccessAsUser.All as well.
    4. Click Add permissions to add the selected permissions to the Configured permissions list.
    5. You can remove the User.Read permission if it's configured. It is not needed.
  3. Next, add Office 365 Exchange Online API application permissions:
    1. Click Add a permission and select APIs my organization uses.
    2. Search and select Office 365 Exchange Online.
    3. Click Application permissions.
    4. Search and select SMTP.SendAsApp.
    5. If you plan to enable inbound email, search and select IMAP.AccessAsApp as well.
    6. Click Add permissions to add the selected permissions to the Configured permissions list.
  4. Now, click Grant admin consent at the top of the Configured permissions table. This is required for client credentials flow.
  5. Lastly, follow these steps to use Exchange Online PowerShell (EXO) to grant your email accounts permission to access the application:
    1. In Entra, go to Identity > Applications > Enterprise applications.
    2. Find the application you registered for Agiloft email and copy the Object ID to the same note you used earlier in the setup.
    3. Now, follow Microsoft's instructions to connect to the EXO module. When you connect, make sure the -UserPrincipalName is an admin user with permission to create service principals and assign access.
    4. Depending on your EXO module version, execute the following commands. Substitute your application's values for the following placeholders:
      • CLIENT_ID - The Application (client) ID.
      • OBJECT_ID - The enterprise application's Object ID.
      • TENANT_ID - For EXO V2 modules, the Directory (tenant) ID.
      • INBOUND_EMAIL_ADDRESS - The email address for the inbound account.
      • OUTBOUND_EMAIL_ADDRESS - The email address for the outbound account.

      EXO V3:

      New-ServicePrincipal -AppId CLIENT_ID -ObjectId OBJECT_ID
      Get-ServicePrincipal -Identity CLIENT_ID
      Add-MailboxPermission -Identity "INBOUND_EMAIL_ADDRESS" -User CLIENT_ID -AccessRights FullAccess
      Add-MailboxPermission -Identity "OUTBOUND_EMAIL_ADDRESS" -User CLIENT_ID -AccessRights FullAccess

      EXO V2 or earlier:

      New-ServicePrincipal -AppId OBJECT_ID -ServiceId CLIENT_ID -Organization TENANT_ID
      Get-ServicePrincipal -Organization CLIENT_ID | fl
      Add-MailboxPermission -Identity "INBOUND_EMAIL_ADDRESS" -User CLIENT_ID -AccessRights FullAccess
      Add-MailboxPermission -Identity "OUTBOUND_EMAIL_ADDRESS" -User CLIENT_ID -AccessRights FullAccess
    5. If there are multiple inbound accounts, you can repeat the following line for each additional account:
      Add-MailboxPermission -Identity "INBOUND_EMAIL_ADDRESS" -User CLIENT_ID -AccessRights FullAccess

Now that the app and access control are configured, you can set up outbound email in Agiloft.

Configure the App for Device Code Flow

Follow the steps below to configure the app for use with device code flow.

  1. In the Entra admin center, click API Permissions in the sidebar.
  2. Click Add a permission and choose Microsoft Graph.
  3. Click Delegated permissions and select all of the OpenId permissions:
    • email
    • openid
    • offline_access
    • profile
  4. In the Select permissions field, search and select SMTP.Send.
  5. If you plan to enable inbound email, search and select IMAP.AccessAsUser.All as well.
  6. Click Add permissions to add the selected permissions to the Configured permissions list.
  7. Next, click Authentication in the sidebar and enable Allow Public Client Flow, then click Save.
  8. At the top of the Authentication page, click Add a platform, click Web, and enter the base URL for your KB as the redirect URL. The base URL usually starts with https:// and ends with.com or other top-level domain. For example: https://example.agiloft.com
  9. Click Configure.

Now that the app is configured, you can set up outbound email in Agiloft.

Set Up Outbound Email

Choose the appropriate steps to follow based on token grant flow:

Use Client Credentials Flow

Follow the steps below to set up the default outbound account in Agiloft. You need the Application (client) ID, Directory (tenant) ID, and Client secret you copied when registering Agiloft in Entra.

  1. In Agiloft, go to Setup > System > Manage Global Variables.
  2. Go to the Variables with Default Values tab and edit the Custom SMTP Configuration Properties variable. To make things easier, maximize the modal window and drag the bottom corner of the Global Variable Value input box to make it bigger.
  3. Paste this text into the Global Variable Value input box. Do not save it yet.
    #main setting and auth
    mail.smtp.auth.mechanisms=XOAUTH2
    mail.agiloft.smtp.auth_flow=skip
     
    #Extended logging for troubleshooting
    mail.agiloft.smtp.trace=false
     
    mail.agiloft.smtp.client.id=CLIENT_ID
    mail.agiloft.smtp.tenant.id=TENANT_ID
     
    #DO NOT specify in case the refresh token long live time is undefined!
    #mail.agiloft.smtp.refresh-token.llt=
     
    # authorization request
    mail.agiloft.smtp.device-auth-request.url=https://login.microsoftonline.com/${mail.agiloft.smtp.tenant.id}/oauth2/v2.0/token
    mail.agiloft.smtp.device-auth-request.payload.1=client_id=${mail.agiloft.smtp.client.id}
    mail.agiloft.smtp.device-auth-request.payload.2=scope=https://outlook.office365.com/.default
    mail.agiloft.smtp.device-auth-request.payload.3=client_secret=CLIENT_SECRET
    mail.agiloft.smtp.device-auth-request.payload.4=grant_type=client_credentials
    mail.agiloft.smtp.device-auth-request.response.user_code.name=code
     
    #device access token request
    mail.agiloft.smtp.device-token.url=https://login.microsoftonline.com/${mail.agiloft.smtp.tenant.id}/oauth2/v2.0/token
    mail.agiloft.smtp.device-token.payload.1=client_id=${mail.agiloft.smtp.client.id}
    mail.agiloft.smtp.device-token.payload.2=scope=https://outlook.office365.com/.default
    mail.agiloft.smtp.device-token.payload.3=client_secret=CLIENT_SECRET
    mail.agiloft.smtp.device-token.payload.4=grant_type=client_credentials
    mail.agiloft.smtp.device-token.response.access_token.name=access_token
    mail.agiloft.smtp.device-token.response.expire.name=expires_in
     
    #new token and refresh token
    mail.agiloft.smtp.device-token-refresh.url=https://login.microsoftonline.com/${mail.agiloft.smtp.tenant.id}/oauth2/v2.0/token
    mail.agiloft.smtp.device-token-refresh.payload.1=client_id=${mail.agiloft.smtp.client.id}
    mail.agiloft.smtp.device-token-refresh.payload.2=scope=https://outlook.office365.com/.default
    mail.agiloft.smtp.device-token-refresh.payload.3=client_secret=CLIENT_SECRET
    mail.agiloft.smtp.device-token-refresh.payload.4=grant_type=client_credentials
    mail.agiloft.smtp.device-token-refresh.response.access_token.name=access_token
    mail.agiloft.smtp.device-token-refresh.response.expire.name=expires_in
  4. Locate these placeholders and replace them with your credentials. Make sure to replace only the placeholder text. Do not remove the equals sign (=) or any other text on the line.
    • CLIENT_ID - Replace CLIENT_ID with your Application (client) ID.
    • TENANT_ID - Replace TENANT_ID with your Directory (tenant) ID.
    • CLIENT_SECRET - In three places, replace CLIENT_SECRET with your client secret value. Make sure you replace all three instances of CLIENT_SECRET.
  5. Click Finish to save your changes.
  6. Now, go to Setup > Email and SMS > Configure Email Server.
  7. Set the SMTP server to: smtp.office365.com
  8. Select STARTTLS and set the Port to 587.
  9. In SMTP login, enter the email address for the outbound account.
  10. Do not enter a password.
  11. In Default outbound email address, enter the email address for the outbound account again. The system will send all outgoing messages from this address.
  12. Select the Reset checkbox at the bottom of the screen, then click Finish.
  13. A confirmation message appears. If you see an error instead, read the message carefully to troubleshoot the problem.
  14. Next, click the link to finish the wizard, then click Configure Email Server.
  15. Enter an email address to send a test message to, then click Finish.

If the test is successful, the browser displays a success message. If the test fails, the browser displays an error message that describes the issue. Review the configuration and make sure the information is complete and correct.

See Next Steps below for guidance on what to do next.

Next Steps

Now that the default outbound account is set up, continue to the appropriate next step:

Use Device Code Flow

Follow the steps below to set up the default outbound account in Agiloft. You need the Application (client) ID and Directory (tenant) ID you copied when registering Agiloft in Entra. You also need the credentials for the outbound email account so you can complete the OAuth registration with Microsoft.

  1. Go to Setup > System > Manage Global Variables.
  2. Go to the Variables with Default Values tab and edit the Custom SMTP Configuration Properties variable. To make things easier, maximize the modal window and drag the bottom corner of the Global Variable Value input box to make it bigger.
  3. Paste this text into the Global Variable Value input box. Do not save it yet.

    #main setting and auth 
    mail.smtp.auth.mechanisms=XOAUTH2
    mail.agiloft.smtp.auth_flow=device
    
    #Extended logging for troubleshooting
    mail.agiloft.smtp.trace=false
      
    mail.agiloft.smtp.client.id=CLIENT_ID
    mail.agiloft.smtp.tenant.id=TENANT_ID
    
    #DO NOT specify in case the refresh token long live time is undefined!
    #mail.agiloft.smtp.refresh-token.llt=
      
    #device authorization request
    mail.agiloft.smtp.device-auth-request.url=https://login.microsoftonline.com/${mail.agiloft.smtp.tenant.id}/oauth2/v2.0/devicecode
    mail.agiloft.smtp.device-auth-request.payload.1=client_id=${mail.agiloft.smtp.client.id}
    mail.agiloft.smtp.device-auth-request.payload.2=scope=user.read offline_access openid profile email https://outlook.office365.com/SMTP.Send
    mail.agiloft.smtp.device-auth-request.response.code.name=device_code
    
    #mail.agiloft.smtp.device-auth-request.response.expires_in.name=expires_in
    mail.agiloft.smtp.device-auth-request.response.message.name=message
      
    #device access token request
    mail.agiloft.smtp.device-token.url=https://login.microsoftonline.com/${mail.agiloft.smtp.tenant.id}/oauth2/v2.0/token
    mail.agiloft.smtp.device-token.payload.1=grant_type=urn:ietf:params:oauth:grant-type:device_code
    mail.agiloft.smtp.device-token.payload.2=code=%CODE%
    mail.agiloft.smtp.device-token.payload.3=client_id=${mail.agiloft.smtp.client.id}
    mail.agiloft.smtp.device-token.response.access_token.name=access_token
    mail.agiloft.smtp.device-token.response.expire.name=expires_in
    mail.agiloft.smtp.device-token.response.refresh_token.name=refresh_token
    
    #new token and refresh token
    mail.agiloft.smtp.device-token-refresh.url=https://login.microsoftonline.com/${mail.agiloft.smtp.tenant.id}/oauth2/v2.0/token
    mail.agiloft.smtp.device-token-refresh.payload.1=client_id=${mail.agiloft.smtp.client.id}
    mail.agiloft.smtp.device-token-refresh.payload.2=scope=offline_access https://outlook.office365.com/SMTP.Send
    mail.agiloft.smtp.device-token-refresh.payload.3=redirect_uri=BASE_KB_URI
    mail.agiloft.smtp.device-token-refresh.payload.4=grant_type=refresh_token
    mail.agiloft.smtp.device-token-refresh.payload.5=refresh_token=%REFRESH_TOKEN%
    mail.agiloft.smtp.device-token-refresh.response.access_token.name=access_token
    mail.agiloft.smtp.device-token-refresh.response.expire.name=expires_in
    mail.agiloft.smtp.device-token-refresh.response.refresh_token.name=refresh_token
  4. Locate these two placeholders near the top of the text, and replace them with your credentials:

    • CLIENT_ID - Replace CLIENT_ID with your Application (client) ID.
    • TENANT_ID - Replace TENANT_ID with your Directory (tenant) ID.
  5. Locate this placeholder near the bottom of the text and replace it with the base URI for your KB:
    • BASE_KB_URI - Replace BASE_KB_URI with the base URI for your KB. This is the same value as the redirect URL you specified when configuring the app.  
  6. Click Finish to save your changes.
  7. Now, go to Setup > Email and SMS > Configure Email Server.
  8. Set the SMTP server to: smtp.office365.com
  9. Select STARTTLS and set the Port to 587.
  10. In SMTP login, enter the email address for the outbound account.
  11. Do not enter a password.
  12. In Default outbound email address, enter the email address for the outbound account again. The system will send all outgoing messages from this address.
  13. Select the Reset checkbox at the bottom of the screen and click Finish.
  14. Note the message in red at the top of the screen. Follow the instructions there to complete the authentication. When you sign in to Microsoft, sign in as the user for the outbound email address.
  15. Back in Agiloft, click the link to finish the wizard, then click Configure Email Server.
  16. Enter an email address to send a test message to.
  17. Click Finish to send the test email.

If the test is successful, the browser displays a success message. If the test fails, the browser displays an error message that describes the issue. Review the configuration and make sure the information is complete and correct.

See Next Steps below for guidance on what to do next.

Next Steps

Now that the default outbound account is set up, continue to the appropriate next step:

Set Up Inbound Email

Setting up an inbound email account is done on a per-table basis. We recommend you connect one inbound account for the Contracts table, so correspondence and documents related to contracts are captured in those records. In some cases, you might set up additional inbound accounts for other process tables like Sourcing Events. Each table in which records will be created or updated by email must have its own inbound account. One table can have more than one email account to serve different purposes.

Follow the steps below to set up an inbound email account. The instructions use the Contracts table as an example, but you can follow these steps to configure inbound email for other tables as well.

Choose the appropriate steps to follow based on token grant flow:

Use Client Credentials Flow

Follow the steps below to set up an inbound account in Agiloft. You need the Application (client) ID, Directory (tenant) ID, and Client secret you copied previously.

  1. Go to Setup > Email and SMS > Configure Inbound Email. This list includes all existing inbound email accounts for all tables.
  2. Edit the demo configuration for Contract. If you already configured Contract and are adding another inbound account, select a different demo configuration to modify or click New to create a new configuration
  3. On the Table tab, if the table isn't already selected because this is a new configuration, select the table that will receive inbound email. If you're editing an existing configuration, the table is already selected.
  4. Click Next.
  5. On the Server tab, select IMAP (Microsoft Exchange) and enter: outlook.office365.com
  6. Select SSL/TLS connection and set Custom Port to 993.
  7. Paste this code into the text input box:

    If the input box isn't shown, go to the last tab and click Finish. Then reopen this configuration and return to the Server tab, which now displays the input box.

    #main setting and auth 
    mail.inbound.auth.mechanisms=XOAUTH2
    mail.agiloft.inbound.auth_flow=device
      
    #Extended logging for troubleshooting
    mail.agiloft.inbound.trace=false
     
    mail.agiloft.inbound.client.id=CLIENT_ID
    mail.agiloft.inbound.tenant.id=TENANT_ID
    
    #DO NOT specify in case the refresh token long live time is undefined!
    #mail.agiloft.inbound.refresh-token.llt=
      
    # authorization request
    mail.agiloft.inbound.device-auth-request.url=https://login.microsoftonline.com/${mail.agiloft.inbound.tenant.id}/oauth2/v2.0/token
    mail.agiloft.inbound.device-auth-request.payload.1=client_id=${mail.agiloft.inbound.client.id}
    mail.agiloft.inbound.device-auth-request.payload.2=scope=https://outlook.office365.com/.default
    mail.agiloft.inbound.device-auth-request.payload.3=client_secret=CLIENT_SECRET
    mail.agiloft.inbound.device-auth-request.payload.4=grant_type=client_credentials
    mail.agiloft.inbound.device-auth-request.response.user_code.name=code
        
    #device access token request
    mail.agiloft.inbound.device-token.url=https://login.microsoftonline.com/${mail.agiloft.inbound.tenant.id}/oauth2/v2.0/token
    mail.agiloft.inbound.device-token.payload.1=client_id=${mail.agiloft.inbound.client.id}
    mail.agiloft.inbound.device-token.payload.2=scope=https://outlook.office365.com/.default
    mail.agiloft.inbound.device-token.payload.3=client_secret=CLIENT_SECRET
    mail.agiloft.inbound.device-token.payload.4=grant_type=client_credentials
    mail.agiloft.inbound.device-token.response.access_token.name=access_token
    mail.agiloft.inbound.device-token.response.expire.name=expires_in
        
    #new token and refresh token
    mail.agiloft.inbound.device-token-refresh.url=https://login.microsoftonline.com/${mail.agiloft.inbound.tenant.id}/oauth2/v2.0/token
    mail.agiloft.inbound.device-token-refresh.payload.1=client_id=${mail.agiloft.inbound.client.id}
    mail.agiloft.inbound.device-token-refresh.payload.2=scope=https://outlook.office365.com/.default
    mail.agiloft.inbound.device-token-refresh.payload.3=client_secret=CLIENT_SECRET
    mail.agiloft.inbound.device-token-refresh.payload.4=grant_type=client_credentials
    mail.agiloft.inbound.device-token-refresh.response.access_token.name=access_token
    mail.agiloft.inbound.device-token-refresh.response.expire.name=expires_in
  8. Locate these placeholders and replace them with your credentials. Make sure to replace only the placeholder text. Do not remove the equals sign (=) or any other text on the line:
    • CLIENT_ID - Replace CLIENT_ID with your Application (client) ID.
    • TENANT_ID - Replace TENANT_ID with your Directory (tenant) ID.
    • CLIENT_SECRET - In three places, replace CLIENT_SECRET with your client secret value. Make sure you replace all three instances of CLIENT_SECRET.
  9. Click Next. If the following warning appears, you can safely ignore it:
    Warning. Status: Communication established with GRAPH.
    To sign in, use a web browser to open the page device-auth-request.response.verification_url.name_NOT_DEFINED_OR_NOT_RETURNED and enter the code device-auth-request.response.user_code.name_NOT_DEFINED_OR_NOT_RETURNED to authenticate.
  10. On the Account tab, enter the following:
    1. In the Email and Email Account fields, enter the complete inbound email address.
    2. Leave the Password field empty. If a series of dots has replaced a previously blank password, delete them.
    3. Under Activity, select This account is actively polling for emails. This enables Agiloft to read messages in the mailbox and pull them into the KB. When "Disable this account - do not check for emails" is selected, it means the inbound account still receives messages, but Agiloft won't access them to pull them into the system.
    4. If incoming messages are saved to a folder other than Inbox, enter the folder path where Agiloft should check for incoming emails.
    5. Click Next.
  11. Confirm that a message appears stating the account is valid. If you see an error message, retrace your steps and check your work.
  12. Go to the last tab and click Finish. The default settings on the rest of the tabs are ideal for most use cases, and we don't recommend that you change them.

For more information on how Agiloft checks inbound email, see Inbound Email Processing. See Next Steps below for guidance on what to do next.

Next Steps

Now that an inbound account is set up, continue to the appropriate next step:

Use Device Code Flow

Follow the steps below to set up an inbound account in Agiloft. You need the Application (client) ID and Directory (tenant) ID you copied previously. You also need the credentials for the inbound account so you can complete the OAuth registration with Microsoft.

  1. Go to Setup > Email and SMS > Configure Inbound Email. This list includes all existing inbound email accounts for all tables.
  2. Edit the demo configuration for Contract. If you already configured Contract and are adding another inbound account, select a different demo configuration to modify or click New to create a new configuration
  3. On the Table tab, if the table isn't already selected because this is a new configuration, select the table that will receive inbound email. If you're editing an existing configuration, the table is already selected.
  4. Click Next.
  5. On the Server tab, select IMAP (Microsoft Exchange) and enter: outlook.office365.com
  6. Select SSL/TLS connection and set Custom Port to 993.
  7. Paste this code into the text input box:

    If the input box isn't shown, go to the last tab and click Finish. Then reopen this configuration and return to the Server tab, which now displays the input box.

    #main setting and auth 
    mail.inbound.auth.mechanisms=XOAUTH2
    mail.agiloft.inbound.auth_flow=device
    
    #Extended logging for troubleshooting
    mail.agiloft.inbound.trace=false
    
    mail.agiloft.inbound.client.id=CLIENT_ID
    mail.agiloft.inbound.tenant.id=TENANT_ID
      
    #DO NOT specify in case the refresh token long live time is undefined!
    #mail.agiloft.inbound.refresh-token.llt=
    
    #device authorization request
    mail.agiloft.inbound.device-auth-request.url=https://login.microsoftonline.com/${mail.agiloft.inbound.tenant.id}/oauth2/v2.0/devicecode
    mail.agiloft.inbound.device-auth-request.payload.1=client_id=${mail.agiloft.inbound.client.id}
    mail.agiloft.inbound.device-auth-request.payload.2=scope=user.read offline_access openid profile email https://outlook.office365.com/IMAP.AccessAsUser.All
    mail.agiloft.inbound.device-auth-request.response.code.name=device_code
    #mail.agiloft.inbound.device-auth-request.response.expires_in.name=expires_in
    mail.agiloft.inbound.device-auth-request.response.message.name=message
      
    #device access token request
    mail.agiloft.inbound.device-token.url=https://login.microsoftonline.com/${mail.agiloft.inbound.tenant.id}/oauth2/v2.0/token
    mail.agiloft.inbound.device-token.payload.1=grant_type=urn:ietf:params:oauth:grant-type:device_code
    mail.agiloft.inbound.device-token.payload.2=code=%CODE%
    mail.agiloft.inbound.device-token.payload.3=client_id=${mail.agiloft.inbound.client.id}
    mail.agiloft.inbound.device-token.response.access_token.name=access_token
    mail.agiloft.inbound.device-token.response.expire.name=expires_in
    mail.agiloft.inbound.device-token.response.refresh_token.name=refresh_token
      
    #new token and refresh token
    mail.agiloft.inbound.device-token-refresh.url=https://login.microsoftonline.com/${mail.agiloft.inbound.tenant.id}/oauth2/v2.0/token
    mail.agiloft.inbound.device-token-refresh.payload.1=client_id=${mail.agiloft.inbound.client.id}
    mail.agiloft.inbound.device-token-refresh.payload.2=scope=offline_access https://outlook.office365.com/IMAP.AccessAsUser.All
    mail.agiloft.inbound.device-token-refresh.payload.3=redirect_uri=BASE_KB_URI
    mail.agiloft.inbound.device-token-refresh.payload.4=grant_type=refresh_token
    mail.agiloft.inbound.device-token-refresh.payload.5=refresh_token=%REFRESH_TOKEN%
    mail.agiloft.inbound.device-token-refresh.response.access_token.name=access_token
    mail.agiloft.inbound.device-token-refresh.response.expire.name=expires_in
    mail.agiloft.inbound.device-token-refresh.response.refresh_token.name=refresh_token
  8. Locate these two placeholders near the top of the text, and replace them with your credentials:
    • CLIENT_ID - Replace CLIENT_ID with your Application (client) ID.
    • TENANT_ID - Replace TENANT_ID with your Directory (tenant) ID.
  9. Locate this placeholder near the bottom of the text and replace it with the base URI for your KB:
    • BASE_KB_URI - Replace BASE_KB_URI with the base URI for your KB. This is the same URI you specified when setting up outbound email.
  10. Click Next.
  11. On the Account tab, note the warning message at the top of the screen. Follow the instructions there to complete the authentication. When you sign in to Microsoft, sign in as the user for the inbound email address.
  12. Back in Agiloft on the Account tab, enter the complete inbound email address in the Email and Email Account fields.
  13. Leave the Password field empty. If a series of dots has replaced a previously blank password, delete them.
  14. Under Activity, select This account is actively polling for emails. This enables Agiloft to read messages in the mailbox and pull them into the KB. When "Disable this account - do not check for emails" is selected, it means the inbound account still receives messages, but Agiloft won't access them to pull them into the system.
  15. If incoming messages are saved to a folder other than Inbox, enter the folder path where Agiloft should check for incoming emails.
  16. Click Next and confirm that a message appears stating the account is valid. If you see an error message, retrace your steps and check your work.
  17. Go to the last tab and click Finish. The default settings on the rest of the tabs are ideal for most use cases, and we don't recommend that you change them.

For more information on how Agiloft checks inbound email, see Inbound Email Processing. See Next Steps below for guidance on what to do next.

Next Steps

Now that an inbound account is set up, continue to the appropriate next step: