Emails sent to the system can be configured to create or update records. It's generally a good idea to set up at least one inbound account for each main process table. This way, if the system sends an email and the recipient replies, their reply will come back into the system. You can set up multiple email accounts, one or many for each table, and define individual behaviors for each.

It's also useful to use the table's inbound account as the default outbound account for emails sent from that table. This makes it easy for users to respond to system emails to update records or add correspondence.

Configuring Inbound Accounts

The Inbound Email wizard is used to set up email accounts that handle replies to outbound emails and any emails sent directly to the system. These are usually used to create new records or update existing records by email. Set up at least one inbound account for each main process table in case anyone replies to outbound emails from the table.

In many cases, you'll want to create multiple inbound accounts to handle different situations and make the table work more smoothly. For instance, you might set up a billing@xyz.com email account that maps to a Problem Type of Billing, and a newaccount@xyz.com account that maps to a Problem Type of New Account Setup.

Follow these steps to configure an inbound email account:

1. Navigate 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 the table you're interested in. Otherwise, if there isn't a demo configuration for the table you need, click New. 
3. In the Table tab, if the table isn't already selected, select the table that will receive the inbound email. Then click Next.
4. Navigate through all the tabs listed below. Remember that your changes won't be saved until you click Finish on the final tab.

Server and Account Tabs

These tabs specify the email server and account information. Your settings here depend on the authentication method you use for your email server. In most cases, you already made a choice about how you want to authenticate when you completed the steps in Configure the Email SMTP Server.

Standard Email and Password

If you used the Standard Email and Password method to Configure the Email SMTP Server, you can proceed to the Accounts tab. If you haven't configured the SMTP server yet, do that first and then return to this page.

On the Account tab:

1. Enter the Email address.

2. In the Email Account field, enter the complete username, which may include a domain or other information.

   It is possible to use a shared mailbox for the inbound account if you're using username and password authentication. Shared mailboxes are typically owned by a non-shared account that is used for authentication. Use the shared account in the Email field, use the password for the owner account in the Password field, and combine the two accounts in the Email Account field in this form: accountowner@example.com/sharedmailbox@example.com.

3. Enter the password for the authenticating account.
4. Select the Activity desired for this account. You can use this to disable active use of this account.
5. For IMAP accounts, if desired, enter the folder path where incoming emails should be filed.
6. Click Next. 

The system status message in the Account tab tells you whether the connection to the Inbound server is successful. 

Gmail OAuth 2

If you configured OAuth 2 for Gmail already, or if you are using Gmail:

1. Follow the "Getting Credentials" steps in the Gmail section of Configure the Email SMTP Server to locate your client ID and client secret.
2. Confirm that your Gmail account has IMAP enabled
   1. Go to your Gmail account.
   2. In the top right, click Settings > See all settings.
   3. Click the Forwarding and POP/IMAP tab.
   4. In the "IMAP access" section, select Enable IMAP.
   5. Click Save Changes.
3. Back in your KB, where you should still be in the email configuration wizard, go to the Server tab.
4. Select IMAP and enter imap.gmail.com as the address.
5. Select SSL/TLS connection and set the Custom Port to 993.

6. Paste this code into the text input box:

   mail.inbound.auth.mechanisms=XOAUTH2 mail.agiloft.inbound.auth_flow=manual mail.agiloft.inbound.tenant.id=******** mail.agiloft.inbound.client.id=******** #DO NOT specify in case the refresh token long live time is undefined! #mail.agiloft.inbound.refresh-token.llt= mail.agiloft.inbound.device-auth-request.url=https://accounts.google.com/o/oauth2/v2/auth mail.agiloft.inbound.device-auth-request.payload.1=client_id=${mail.agiloft.inbound.client.id} mail.agiloft.inbound.device-auth-request.payload.2=scope=email profile openid https://mail.google.com/ mail.agiloft.inbound.device-auth-request.payload.3=response_type=code #check hotlink server root points to proper location mail.agiloft.inbound.device-auth-request.payload.4=redirect_uri=%REDIRECT_URI% mail.agiloft.inbound.device-auth-request.payload.5=state=%STATE% mail.agiloft.inbound.device-auth-request.payload.6=access_type=offline mail.agiloft.inbound.device-auth-request.payload.7=prompt=consent select_account mail.agiloft.inbound.device-auth-request.response.user_code.name=user_code mail.agiloft.inbound.device-auth-request.response.verification_url.name=verification_url #exchange auth code for token mail.agiloft.inbound.device-token.url=https://oauth2.googleapis.com/token mail.agiloft.inbound.device-token.payload.1=grant_type=authorization_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.payload.4=client_secret=${mail.agiloft.inbound.tenant.id} mail.agiloft.inbound.device-token.payload.5=state=%STATE% mail.agiloft.inbound.device-token.payload.6=redirect_uri=%REDIRECT_URI% 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://oauth2.googleapis.com/token mail.agiloft.inbound.device-token-refresh.payload.1=client_id=${mail.agiloft.inbound.client.id} mail.agiloft.inbound.device-token-refresh.payload.2=grant_type=refresh_token mail.agiloft.inbound.device-token-refresh.payload.3=client_secret=${mail.agiloft.inbound.tenant.id} mail.agiloft.inbound.device-token-refresh.payload.4=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

7. Locate these two lines near the top of the text, and replace the asterisks with your credentials:

   1. mail.agiloft.smtp.tenant.id=*********** - Replace the asterisks with your client secret.

   2. mail.agiloft.smtp.client.id=*********** - Replace the asterisks with your client ID.

8. Click Next. Click the link that appears above the status message to finish the OAuth registration.

   If clicking the link doesn't work, skip to step 13, save your work, and then go back to Setup > Email and SMS > Configure Inbound Email and edit this configuration again. Click Next to proceed to the Account tab and click the link again.

9. Select the appropriate account.
10. In the "Google hasn't verified this app" message, click the Continue link.
11. Select the Read, compose, send... option and click Continue.
12. Confirm that it shows Success, and then close the tab.
13. Back in , on the Account tab:
    1. Enter the full email address in both the Email and Email Account fields.
    2. Leave the password field empty.
    3. Enter the Client ID and Client Secret you used in step 7.

Microsoft OAuth 2 without EWS

If you configured OAuth 2 for Microsoft, and you were not instructed to use the EWS setup:

1. Follow the steps in Configure the Email SMTP Server to locate your Application ID and Directory ID.
2. If you want to use a shared mailbox for this account, take a moment now to log in to the Exchange online admin center and go to Mailboxes > select the shared mailbox > Delegation. Make sure the user account has "Read and manage" set to full access.
3. Back in your KB, where you should still be in the email configuration wizard, go to the Server tab.
4. Select IMAP and enter outlook.office365.com as the address.
5. Select SSL/TLS connection and set the Custom Port to 993.

6. Paste this code into the text 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.tenant.id=*********** mail.agiloft.inbound.client.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=http://localhost 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

7. Locate these two lines near the top of the text, and replace the asterisks with your credentials:

   1. mail.agiloft.smtp.tenant.id=*********** - Replace the asterisks with your Directory ID.

   2. mail.agiloft.smtp.client.id=*********** - Replace the asterisks with your Application ID.

8. Click Next. This shows a warning message with steps to complete the authentication. If you're using a shared mailbox, authenticate with the user account, not the shared account.
9. Note the code in the warning message, and then copy the URL from the warning and paste it into a new browser tab.
10. In the page that loads, paste the code from the warning message.
11. Click Next, log in with the appropriate Microsoft credentials, and click Continue to confirm.
12. Return to and go to the Account tab.
    1. Complete the Email and Email Account fields with the full email address. IMAP must be enabled for account you enter. If you're using a shared mailbox, enter the shared account information here.
    2. Leave the password field empty.
13. Configure the rest of your preferences. If you want to set the other preferences later, select “Disable this account” and go directly to the Filters tab so you can click Finish.

Microsoft EWS with OAuth

If you are instructed to use the EWS method instead, follow these steps instead of the ones above.

This method uses EWS to meet Microsoft's OAuth 2.0 authentication requirements. If possible, it is usually better to accomplish this using the OAuth 2 setup described in Configure the Email SMTP Server and Inbound Email Accounts, because that configuration is more secure and allows both inbound and outbound authentication. However, if you can't use that method for some reason, you can use this method to authenticate inbound email.

Configure  in Entra ID

Configuring  as an application in Entra requires registering your system with Entra, identifying the application as an authentication tool in Entra, and adding access permissions. 

First, you need to register your   system with Entra. As you follow the steps, you can also refer to Microsoft's setup instructions if any of the options you see differ from those described here.

1. Sign in to the Entra portal with the appropriate organization account.
2. If your account has access to multiple tenants, select your account in the upper right corner and set your session to the appropriate AD 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 " Application for OAuth2."
5. Select an option for who can use the application. This choice depends on how you use Entra. If you created an Entra account and tenant only for this purpose, select "Accounts in this organizational directory only."
6. Leave the default Redirect URI settings.
7. Click Register. The portal automatically directs you to the overview page for the  application.

With the application registered, you can gather the necessary identifying information to use the application with Entra as an authentication tool.

1. In the sidebar, click Certificates & secrets.
2. Click New client secret.
3. Give the Client Secret a descriptive name, such as " EWS Integration."
4. Set it to the maximum expiration of 24 months.
5. Click Add. The secret now appears in the list.
6. Copy the secret's value into a note or document. Make sure to take the value, not the ID.
7. In the portal sidebar, click Overview to return to the overview page for the application.
8. Copy the Application ID value into your note. This is the Client ID you need in .
9. Copy the Directory ID value into your note. This is the Tenant ID you need in .

Before you leave the portal, add access permission for the application:

1. Inside your Agiloft app registration, click Manifest on the sidebar.

2. Locate the requiredResourceAccess property in the manifest, and add the following inside the square [] brackets, at the bottom of the list of properties. Note that the comma at the top should be positioned next to the last } in the existing code, so that in the finished product you have a line reading }, and then the rest of the code being added.

   , { "resourceAppId": "00000002-0000-0ff1-ce00-000000000000", "resourceAccess": [ { "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40", "type": "Role" } ] }

   Take a moment to double check your work and make sure the code has been added in the correct location, as described. Adding this code incorrectly is a common mistake.

3. Click Save.
4. Click API permissions in the sidebar.
5. Confirm the full_access_as_app permission is listed.
6. Click Grant admin consent, located next to the Add a permission button. 

Set Up Inbound Accounts

With the application registered and configured in Entra, you can use it to authenticate inbound email addresses in . You must complete this setup for each inbound account that uses an Office 365 or Microsoft Exchange email address:

1. Back in your KB, where you should still be in the email configuration wizard in Setup > Email and SMS > Configure Inbound Email, confirm that the selection in the Table tab is correct.
2. On the Server tab:
   1. Select IMAP.
   2. Enter EWS:outlook.office365.com/ews/Exchange.asmx for the address.
   3. Enable SSL/TLS connection.
   4. Set the custom port option to 443.
3. On the Account tab:
   1. Enter the full email address. If you're using a shared mailbox, enter the shared mailbox address.
   2. Leave the password field empty.
   3. Enter the Tenant ID, Client ID, and Client Secret you copied from your Entra application page.
4. If you need to access multiple mailboxes with this configuration, you can do so on the Account tab with the Additional Users field. In the field, enter each additional email address, separating addresses with semicolons. For example: email1@email.com; email2@email.com; email3@email.com

Accounts

The system status message in the Account tab tells you whether the connection to the Inbound server is successful. 

To continue setup:

1. Enter the Email address.

2. In the Email Account field, enter the complete username, which may include a domain or other information.

   It is possible to use a shared mailbox for the inbound account. Shared mailboxes are typically owned by a non-shared account that is used for authentication. Use the shared account in the Email field, use the password for the owner account in the Password field, and combine the two accounts in the Email Account field in this form: accountowner@example.com/sharedmailbox@example.com.

3. Enter the password for the authenticating account. For OAuth 2 with Gmail or Microsoft, do not enter a password, and if a series of dots has replaced a previously blank password, delete them.  If you are using Gmail without OAuth 2, complete these steps to generate the password you need to enter here:
   1. Log in to the Gmail account, click the user icon, and click Manage your Google Account.
   2. Go to the Security tab in the left pane.
   3. Under Signing in to Google, click 2-Step Verification. Follow the instructions to enable it.
   4. Return to the Security tab and click App Passwords.
   5. Select Other and enter your server hostname, including https:// and .com. For example, https://example.agiloft.com, or https://trial99-nsc.agiloft.com. 
   6. Click Generate. 
   7. Copy the generated password, making sure to select complete password without any spaces. Then, return to and paste this password for step 3.
4. Select the Activity desired for this account. You can use this to disable active use of this account.
5. For IMAP accounts, if desired, enter the folder path where incoming emails should be filed.
6. Click Next. 

Record Mapping

To let records be created from inbound emails, configure the settings on the Record Mapping tab. Define which fields are used to store the email data, including the subject of the email, sender's email address, email body, and any attached files. 

1. Define how to handle the sender and recipient values, including the name and email address of the sender and the people on the To and CC lines. Email addresses can be stored separately from the name, which can be useful to prevent errors due to name-sensitive email recognition.

   If you use the email address to try to match a contact record's Email field, select the option to strip out all text other than the email address.

2. Select options for storing the message, attachments, and images. 
3. Select any fields you want to set automatically. For example, you might configure an address for urgent-outage@yourcompany.com to automatically set Priority to 1.
4. Click Next.

Email Updates

Choose if and how records are updated by email.

1. Select where to store the body of the email. It's usually best to append the body of the email into an Append Only field. This way it is native to the table and can be sent with the other fields in an email notification. For instance, you can create the following email notification: "An email was received from $updated_by and here is its content: $additional_notes_latest."
2. Determine whether to include quoted content. If you choose to remove quoted content, the system truncates any part of the email that follows the hidden code, if a hidden code is configured in the outbound settings. This is intended to remove the email conversation quoted at the bottom, to avoid duplicating messages over and over in a long thread.
3. At the bottom, select options to determine where attached images and files are stored.
4. Click Next.

Email Parsing 

Email parsing makes it possible to update specific fields based on text held in the email body. When using parsing, you must define a delimiter string the system will use to start and end parsing. For example, if "Agiloft Details" is defined as the delimiter, the following email will set the Manager, Comments and Priority fields in the record:

For more information, see Email Parsing.

1. Select the Enable field parsing for inbound email checkbox.
2. In the text field, enter the delimiter string the system will use to start and end parsing. In the example above, you would enter Agiloft Details.
3. Select the language.
4. Determine whether parsing replaces or adds to the field values set by your configuration on previous tabs.
5. Select options for handling errors, invalid fields, and permission issues. For each option, you can also choose to email administrators when the issue occurs.
6. If you chose to email administrators about any issues, complete the fields to set the email address for the administrators and the contents of the message.
7. Click Next.

Access 

This tab defines options such as whether or not record creation by email is allowed, what to do when the sender is not recognized, who to notify if an email is rejected, and how long emails are left on the server after they have been retrieved. 

1. In Record Creation, select or clear the Enable creation of records by email checkbox.
2. If you clear the checkbox, you can optionally select the option to send a reply when someone attempts to create a record by email. For example, you might send a message saying, "Records cannot be created by email. Please log in to the system to create a new record."
3. Next, determine what happens if the email address trying to create a record doesn't match an email in the system. You can either:

   • Create a new record using a specified existing user's account. You can also select this option with an additional limitation to process emails only from addresses with a specified domain. To use this feature, enter the allowed domains in the field, separating each domain with ;.

     If you allow emails from unknown users, choose your guest account and its group permissions carefully. Be sure the guest group has "create own" access to the table and the fields you have mapped. Email updates do not check the permissions of the sender; they are applied to the correct records without limitation. This is to enable people who were cc'd about the original ticket to be able to successfully reply to the system even if they are not users.

   • Discard the email. This way, only existing users can create records by email, and they can only do so from an email address linked to their user record.
4. Complete the same options for record updates.
5. If desired, select the option to forward discarded emails and specify an addressee, message content, and whether to include attachments.
6. Finally, determine how long to keep emails on the server. It's generally best to leave email on the server for one or two days to allow time for troubleshooting.
7. Click Next.

Filters 

Use filters to prevent email loops and spam from automatic email replies. For example, if a user has an automatic out-of-office reply set up and the system sends the user an email, the automatic reply can trigger additional system responses endlessly.

1. Select the options for handling bounced emails. In most cases, all the options in this section should be selected to prevent loops that generate records endlessly. If you choose to clear any of the checkboxes, make sure to carefully check all inbound processing and automatic responses beforehand.
   
2. If desired, disable automatic responses to email from specific addresses or containing certain phrases. If an automatic response is disabled, the system still creates a record based on the email, but no response is sent to the sender.
3. If desired, discard email from specific addresses or containing certain phrases. This prevents a record from being created and simply discards the email.
4. Discontinue auto-responding by setting the number of messages that can be processed from a single address in a specified time frame.
5. Keep email subjects tidy by truncating Re: and Fwd: subject prefixes after a specified amount.
6. Finally, if you want to apply your Filter changes to all inbound accounts, you can select the Update all inbound email filters checkbox.
7. Click Finish to save your changes.

Checking Inbound Accounts 

By default,, checks inbound email accounts and downloads new messages every minute. New messages are copied into the Communications table for the associated email account's table. When an email is received by the system, it looks for the encrypted ID in the subject or header to determine if it is a reply to an existing record. If it is, then the email is treated as a record update. If there is no encrypted ID found, it is treated as an email that will create a new record if record creation is enabled. 

Depending on the contents of a particular email, the following processes occur:

1. If a Record ID is encoded in the subject or header, the system recognizes the email as an update to that record. Depending on your email settings, parts of the email can be copied to the Additional Notes field of the record, and change the Updated By field. When a record ID is encoded in the email, does not check the permissions of the sender. This allows external users to respond, for instance if they were cc'd on a ticket, and saves their update to the record.
2. If no Record ID is encoded and the sender's email matches a user in the Contacts table, and record creation is allowed for that inbound account, and the user has the appropriate permissions, the system creates a new record under that user's name.
3. If no Record ID is present and the sender is not recognized, the system ignores or rejects the email, or creates a new record under a user account that you specify during setup. Guest accounts are usually used to create new records in this case.

You can alter the frequency that  checks for inbound emails using the Checking frequency for inbound emails (minutes) global variable.

Troubleshooting Inbound Accounts

The outbound email header contains encrypted information about the table and record ID from which it was sent. Because MS Exchange strips out headers when sending internal emails, we also add this encrypted information to the subject line of emails as a backup.

The outbound email header also contains complete details on how and why the email was sent, such as server URL, KB, table, and rule or workflow ID that initiated the email. This information is displayed in the communication record. It can also be viewed in an email received in Outlook by clicking View > Options on older releases of Outlook, or File > Properties and scrolling through the Internet Header display. This is useful for testing or troubleshooting when you receive emails without knowing why.

Inbound Email Security