Page tree

Email Setup with Microsoft Graph

Microsoft Graph offers a method of securely accessing data from Microsoft services. Agiloft can be configured to access Exchange Online mailboxes via the Microsoft Graph API with OAuth 2.0. 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 access your email with Microsoft Graph protocol. SMTP authentication is not used.

Prerequisites

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

  • 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 role-based access control for applications.
  • 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, you need 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 Graph 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 Agiloft 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 repeat this step to generate a new secret and update your email configuration 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.
  10. If you plan to use client credentials flow, you can also click API Permissions in the sidebar and remove the User.Read permission if it's configured. It is not needed.

Now that Agiloft is registered, the next step is to configure access to 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 role-based access control for client credentials flow. You use the Exchange Online PowerShell (EXO) module to configure permissions so your email accounts can access the application. The commands apply the Mail.Send permission to the outbound account and Mail.ReadWrite to the inbound account, as Write permission is required for Agiloft to mark items as Read.

  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, scopes, and roles.
  4. Execute the following commands, substituting your application's values for the following placeholders:
    • CLIENT_ID - The Application (client) ID.
    • OBJECT_ID - The enterprise application's Object ID.
    • INBOUND_EMAIL_ADDRESS - The email address for the inbound account.
    • OUTBOUND_EMAIL_ADDRESS - The email address for the outbound account.
    $APPID = 'CLIENT_ID'
    $OBJECTID = 'OBJECT_ID'
    $DISPLAYNAME = 'Agiloft'
    
    $SVCINBOUND = 'INBOUND_EMAIL_ADDRESS' 
    $SVCOUTBOUND = 'OUTBOUND_EMAIL_ADDRESS'
    
    $SVCINBOUNDALIAS = (Get-Mailbox -Anr $SVCINBOUND ).Alias
    $SVCOUTBOUNDALIAS = (Get-Mailbox -Anr $SVCOUTBOUND ).Alias
    
    New-ServicePrincipal -AppId $APPID -ObjectId $OBJECTID -DisplayName "Agiloft Graph Email"
    New-ManagementScope -Name "Agiloft Email Outbound" -RecipientRestrictionFilter "Alias -eq '$SVCOUTBOUNDALIAS'"
    New-ManagementRoleAssignment -Name "Agiloft Email Outbound Assignment" -App $APPID -Role "Application Mail.Send" -CustomResourceScope "Agiloft Email Outbound"
    New-ManagementScope -Name "Agiloft Email Inbound" -RecipientRestrictionFilter "Alias -eq '$SVCINBOUNDALIAS'"
    New-ManagementRoleAssignment -Name "Agiloft Email Inbound Assignment" -App $APPID -Role "Application Mail.ReadWrite" -CustomResourceScope "Agiloft Email Inbound"
  5. If there are multiple inbound accounts, you can repeat the following lines for each additional account:
    $SVCINBOUND = 'INBOUND_EMAIL_ADDRESS'
    $SVCINBOUNDALIAS = (Get-Mailbox -Anr $SVCINBOUND ).Alias
    New-ManagementScope -Name "Agiloft Email Inbound" -RecipientRestrictionFilter "Alias -eq '$SVCINBOUNDALIAS'"
    New-ManagementRoleAssignment -Name "Agiloft Email Inbound Assignment" -App $APPID -Role "Application Mail.ReadWrite" -CustomResourceScope "Agiloft Email Inbound"
  6. You can test the new role and scope settings by running the following commands:
    Test-ServicePrincipalAuthorization -Identity $APPID -Resource $SVCINBOUND
    Test-ServicePrincipalAuthorization -Identity $APPID -Resource $SVCOUTBOUND

    Output of PowerShell test commands

Now that access control is in place, 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 Mail.Send.
  5. If you plan to enable inbound email, search and select Mail.ReadWrite and 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://graph.microsoft.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://graph.microsoft.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://graph.microsoft.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: GRAPH
  8. Leave the connection type and port at their default settings. They're not used by this server configuration.
  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 outbound email address 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. 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 code into the text input box. Do not save it yet.

    mail.smtp.auth.mechanisms=XOAUTH2
    mail.agiloft.smtp.auth_flow=device
     
    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/Mail.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=user.read offline_access openid profile email https://outlook.office365.com/Mail.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. 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.

  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. The base URI usually starts with https:// and ends with .com or other top-level domain. For example: https://example.agiloft.com
  6. Click Finish to save your changes.
  7. Go to Setup > Email and SMS > Configure Email Server.
  8. Enter the following:
    1. Set the SMTP server to: GRAPH
    2. Select SSL/TLS connection and set the Port to 465.
    3. In SMTP login, enter the email address for the outbound account.
    4. Do not enter a password.
    5. In Default outbound email address, enter the outbound email address again. The system will send all outgoing messages from this address.
  9. Select the Reset checkbox at the bottom of the screen and click Finish.
  10. Note the message in red at the top of the screen. Follow the instructions there to complete authentication. Make sure you sign in to Microsoft as the user account for the outbound email address.
  11. Back in Agiloft, click the link to finish the wizard, then click Configure Email Server.
  12. Enter an email address to send a test message to.
  13. 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 > Inbound Email Accounts. 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 and enter: GRAPH
  6. Select the SSL/TLS connection checkbox.
  7. Confirm that Custom Port is set to 993.
  8. 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=skip
      
    # 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://graph.microsoft.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://graph.microsoft.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://graph.microsoft.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
  9. Locate each instance of these placeholders, 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.
    • CLIENT_SECRET - In three places, replace CLIENT_SECRET with your client secret value. Make sure you replace all three instances of CLIENT_SECRET.
  10. Click Next. If the following warning appears, you can safely ignore it:
    Warning. Status: Communication established with GRAPH: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.
  11. 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.
  12. Confirm that a message appears stating the account is valid. If you see an error message, retrace your steps and check your work.
  13. 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 email account so you can complete the OAuth registration with Microsoft.

  1. Go to Setup > Email and SMS > Inbound Email Accounts. 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: GRAPH:GRAPH
  6. Leave
  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.

    mail.inbound.auth.mechanisms=XOAUTH2
    mail.agiloft.inbound.auth_flow=device
    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/Mail.Read
    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=user.read offline_access openid profile email https://outlook.office.com/Mail.ReadWrite
    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 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 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.
  13. Confirm that a message appears stating the account is valid. If you see an error message, retrace your steps and check your work.
  14. 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: