Page tree

Email Troubleshooting

Use this page as a guide to help you maintain your email configuration and resolve email issues. It includes tips on getting diagnostic information and lists possible causes and solutions for problems.

Examining Email Headers

The outbound email header contains encrypted information about the table and record ID from which it was sent. It 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. Because Microsoft Exchange strips out headers when sending internal emails, we also add this encrypted information to the subject line of emails as a backup.

The header 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.

Testing the Outbound Connection

To test the outbound connection, you can send a test email from Agiloft. The test checks outbound connectivity and displays an error message if there's a problem. To send a test email:

  1. Go to Setup > Email and SMS > Configure Email Server.
  2. Under Enter email address to send a test message, type your email address.
  3. Click Finish to send the email.

If the test is successful, the browser displays a success message, and you'll receive an email. If the test fails, the browser displays an error message describing the issue. If the system says the message was sent successfully but it doesn't arrive in your inbox, there may be an issue with your outbound server.

Outbound Connection Failure Handling

By default, if the outbound server connection fails, Agiloft caches failed emails for 5 days and attempts to resend them every 30 minutes. After 5 days of failed attempts,  Agiloft no longer attempts to resend that email. To change the default behavior of the system:

Testing an Inbound Connection

To test an inbound connection, follow these steps:

  1. Go to Setup > Email and SMS > Configure Inbound Mail.
  2. Edit the configuration for the account you want to troubleshoot.
  3. On the Table tab, click Next to go to the Server tab.
  4. Click Next to go to the Account tab. Agiloft verifies the connection to the server and displays either a success message or error at the top of the screen.
  5. Click Next again. Agiloft verifies the account and displays either an account is valid message or an error about why the connection failed.

Any errors you receive about the server or account connection are the most relevant messages to start with for troubleshooting.

Inbound Email Processing

By default, Agiloft 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, Agiloft 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  Agiloft checks for inbound emails using the Checking frequency for inbound emails (minutes) global variable.

Most email types ignore the "Mark as Read" flag that you can manually apply to new emails, so any emails you flag this way are still treated as new emails. The exception is email accounts configured with IMAP, which respects the "Mark as Read" flag. For IMAP accounts, every 45 minutes,  Agiloft automatically checks for new email using a method that looks for all emails, regardless of the "Mark as Read" flag, so any emails flagged this way are still received and processed as new emails.

Replacing an Expired Client Secret

Follow the steps below if you need to update your email configuration to replace an expired client secret. The process involves editing the outbound and inbound email configuration properties in Agiloft and re-authenticating the application with the new secret. 

  1. First, generate a new client secret according to your email provider's instructions. Copy the secret value to a note so you can refer to it later.
  2. In Agiloft, go to Setup > System > Manage Global Variables.
  3. On the Customized Variables tab, 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.
  4. In the Global Variable Value, find each instance of client_secret=<existing_value> and replace the existing value with the new secret value. Make sure to replace only the secret text. Do not remove the equals sign (=) or any other text on the line.
    For Microsoft configurations, client_secret appears three times in Global Variable Value. Make sure you replace all instances of the secret.
  5. When you've completed the edits, click Finish to save your changes.
  6. Now, follow these steps to re-authenticate outbound email using the new secret:
    1. Go to Setup > Email and SMS > Configure Email Server.
    2. At the bottom of the screen, select the Reset checkbox.
    3. Click Finish. A confirmation message appears, saying the connection was successful. If you see an error instead, read the message carefully to troubleshoot the problem.
  7. To double-check the outbound configuration, it's a good idea to send a test email:
    1. Under the confirmation message, click the link to finish the wizard, then click Configure Email Server.
    2. Enter an email address to send a test message to.
    3. 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 your changes are complete and correct.
  8. Next, if inbound email is enabled, follow these steps to update the configuration and re-authenticate:
    1. Go to Setup > Email and SMS > Inbound Email Accounts.
    2. Edit the configuration for the table where inbound email is enabled. Typically, it's the Contract configuration.
    3. On the Table tab, click Next.
    4. On the Server tab in the configuration properties text box, find each instance of client_secret=<existing_value> and replace the existing value with the new secret value. Make sure to replace only the secret text. Do not remove the equals sign (=) or any other text on the line.
      For Microsoft configurations, client_secret appears three times in the text. Make sure you replace all instances of the secret.
    5. Select the Reset checkbox at the bottom of the screen, then click Next. A warning is displayed that says communication was established. You can safely ignore the rest of the message.
    6. Click Next, then click Next again on the Account tab.
    7. Confirm that a message appears stating the account is valid. If you see an error message, retrace your steps and check your work.
    8. Go to the last tab and click Finish.
    9. If you have additional inbound accounts, repeat steps b – h for each table that has an inbound account.

Your email configuration is now updated with the new secret.

Resetting the OAuth Token

If you edit your email configuration to replace an email address, or if you change an existing email account, such as to reset the password, the OAuth token must be reset in the system. Follow the steps below to reset and re-authenticate after changing an email account.

To reset the outbound account:

  1. Go to Setup > Email and SMS > Configure Email Server.
  2. Click the Reset checkbox at the bottom of the screen.
  3. Click Finish.
  4. Depending on your email provider and token grant flow, the browser displays one of the following messages:
    • A confirmation that the connection is successful. In this case, go to the next step.
    • A prompt to finish the OAuth registration. In this case, follow the instructions to sign in with your email provider as the user for the outbound email address. Confirm that the authentication is successful.
  5. Finally, it's a good idea to send a test message to confirm the reset:
    1. In Agiloft, click the link to finish the wizard, then click Configure Email Server.
    2. Enter an email address to send a test message to.
    3. Click Finish to send the test email.

To reset an inbound account:

  1. Go to Setup > Email and SMS > Inbound Email Accounts.
  2. Edit the configuration for the table where inbound email is enabled. Typically, it's the Contract configuration.
  3. On the Table tab, click Next.
  4. On the Server tab, click the Reset checkbox at the bottom of the screen, then click Next.
  5. On the Account tab, depending on your email provider and token grant flow, one of the following messages is displayed at the top of the screen:
    • A confirmation that communication is successful. In this case, go to the next step.
    • A prompt to finish the OAuth registration. In this case, follow the instructions to sign in with your email provider as the user for the inbound email address. Confirm that the authentication is successful.
  6. In Agiloft on the Account tab, click Next.
  7. Confirm that a message appears stating the account is valid.
  8. Go to the last tab and click Finish.

Troubleshooting Symptoms and Errors

This section lists possible causes and solutions for email issues.

Some Emails won't Send

If certain emails aren't being sent, check the list below for possible causes and edit the emails or change settings as needed.

  • You must have a valid outbound email address when sending mail, or emails won't be sent. This is important to remember if you use a field value as the outbound address, rather than an explicit email address. Do not use a field value unless you can be sure that the field always has a value.
  • Emails won't be sent if they contain attachments that are cumulatively larger than the size defined in the Max Email Attach Size global variable or if the body of the email is larger than the size defined in the Max Email Body Size (without attachments) global variable. If an email is not sent due to the attachment or body size, the sender receives an error message. Similarly, even if an email's body size and attachments size falls within their respective limits, your email won't be successfully sent if its overall size (body and attachments) exceeds the limits set by your server.

No Emails are Received

When you don't think any emails are being sent, it's helpful to check the outbound connection by sending a test email from Agiloft. If there's a problem, the test results in an error message that can help you diagnose the issue.

Unexpected or Duplicate Emails are Received

If you're receiving emails that you don't expect, check the list below for possible causes and resolutions:

  • It's possible that the mail daemons for a test KB are inadvertently running when they should be disabled. To check if that's the case, view the email header for an unexpected message and see which KB sent it. If it's not the KB you expect, you may need to disable email in that environment.
  • If you're receiving duplicate emails and they're being sent from the expected KB, it might mean the email is being sent by a rule and an unexpected API trigger caused the rule to run multiple times. Check the message header for the duplicate emails to see which rule sent the message. Then review the rule configuration in Agiloft and make changes as needed. For help troubleshooting rules, see Troubleshooting Rules.

Access is denied

For Microsoft integrations with client credentials flow, if the Account tab in the inbound configuration shows an error message like the one below, it means communication was established with the server but the email account you specified doesn't have permission to access the Agiloft application. 

Error. Status: Able to contact [server], but unable to establish successful email communication. Please check the account name and password on the Account tab.
[Error code: ErrorAccessDenied Error message: Access is denied. Check credentials and try again. GET https://graph.microsoft.com/v1.0/users/[address]/mailFolders/inbox SdkVersion : graph-java/v4.0.0 403 : Forbidden

To correct the issue, configure access with Exchange Online PowerShell. For Graph, follow these instructions. For OAuth 2.0, follow the instructions here.

Problem with oauth: User or admin has not consented

For Microsoft integrations, if the inbound configuration shows an error message like the one below, it means admin consent was not granted for the application permissions in Entra.

Error. Status: Able to contact [server], but unable to establish successful email communication. Please check the account name and password on the Account tab. [Cause: java.rmi.RemoteException: Problem with oauth authentication: {error=invalid_grant, error_description=AADSTS65001: The user or administrator has not consented to use the application...

To resolve the issue, follow Microsoft's instructions to grant admin consent in the Entra admin center.

Problem with oauth: Token expired or revoked - User might have changed password

If the inbound or outbound configuration shows an error message similar to the one above, it indicates that the password for the email account was changed, and the OAuth token needs to be reset in Agiloft. To correct the problem, follow the instructions in Resetting the OAuth Token.

Problem with oauth: Invalid request - Request is malformed or invalid

If the inbound or outbound configuration shows an error message like the one above, it usually means the request includes an invalid authentication token. This can occur if the email account was changed, such as if the password was reset. To resolve the issue, refresh the OAuth token in Agiloft by following the instructions in Resetting the OAuth Token.