Help

Page tree

Configure the Email SMTP Server

To use email with  Agiloft, you need to have an email server set up. You can set up SMTP with an email address and password, the credentials for the default SMTP account; with OAuth 2.0 credentials from Gmail; or with OAuth 2.0 credentials from Microsoft.

If you are using  Agiloft's hosted service, the outbound email server is already configured. However, you might want to set or change the default outbound address for your system, even if the other settings have been configured for you.

Standard Email and Password

This choice is the easiest to set up, but it does not work with Gmail or most Microsoft accounts. If your outbound email address is a Gmail or Microsoft address, set up SMTP using the corresponding OAuth 2.0 authentication method below. The one exception is Microsoft Exchange on-premise accounts, which still support basic authentication.

To use the standard login and password configuration:

  1. To configure the Email outbound SMTP server, go to Setup > Email and SMS > Configure Email Server.

  2. Review the SMTP server listed. By default, the SMTP Server is set to localhost, which will work if Sendmail is installed on your server. Otherwise, you will need to identify an SMTP server to use. 

  3. Review the SMTP options selected below the server address and make adjustments if necessary. The SSL/TLS option is used if the server supports encryption, for maximum security. If this does not work, the STARTTSL option often works, as it negotiates security after the initial exchange. 
  4. Enter the SMTP login, which is the first half of the email address for the default SMTP account. The login should not include the full address; only enter the part that precedes the @ sign.
  5. Enter the SMTP password for the account.

  6. Define the Default outbound email address for your system. The outbound address does not have to be a functional email address, but it must be formatted like an email address for validation purposes. If you do plan to send emails using this address as the From address, it's best to match the email server's domain so that the emails are less likely to be marked as spam.

    Remember, if you are using an email address with a Gmail or Microsoft domain, you must use the Gmail or Microsoft setup instead.

  7. Test your email setup by entering your email address in the text box and clicking Finish.

Gmail OAuth 2.0 Authentication

This setup is the foundation for both inbound and outbound email using Gmail authentication, although inbound email requires additional setup covered in Inbound Email Accounts.

Getting Credentials

First, obtain OAuth 2.0 credentials from Google. You'll need both a client ID and a client secret. These steps guide you through options that are also documented by Google here.

  1. Go to the Google API Console and log in with the proper account.
  2. Go to Select a project > New Project. Give the project a name and create it. At the top of the screen, confirm the project name is selected in the drop-down.
  3. On the left sidebar, under APIs and Services, click OAuth Consent.
  4. Click Create credentials.
  5. Select Internal and click Create. Note that if you are using a free or personal account for testing purposes, you can only select External, which will also allow you to use Gmail authentication, but will require re-authentication every seven days.
  6. Complete the required form.
  7. On the next screen, click Add or remove scopes, and then click Next.
  8. In the Manually add scopes section, enter https://mail.google.com in the field.
  9. Click Add to Table. On the table, select the /userinfo.email, /userinfo.profile, openid, and mail.google.com scopes.
  10. Click Update, then Save and Continue.
  11. On the next tab, configure a test user with the email account you will use with Agiloft. Save and Continue.
  12. On the dashboard, check the OAuth rate limits. 1 day is enough.
  13. Go to Credentials in the left menu, click Create Credentials, select OAuth client ID, and then select Web Application for Application Type.
  14. Next, update the Authorized Redirect URIs. First, in your KB, go to Setup > System > Manage Global Variables, locate hotlinkserverroot and copy the contents of the variable. If the value is empty, enter the URL of your KB, beginning with https: and ending right before /ui, copy the result, and then save the changes. Then, back in the Google configuration window, paste that value. Finally, add this to the end of the URL: /ui/emailoauth2
  15. Click Create.
  16. Copy the generated client ID and client secret. Store these in a note so you can copy them later.
  17. Finally, enable the API for your project:
    1. Open the API Library in the Google API Console.
    2. If prompted, select the project you created.
    3. Use the search function to find the Gmail API, and then click Enable for it.
    4. If prompted, enable billing and read and accept the terms of service.

Configuring SMTP with Gmail

Now that you have the credentials, you can set up SMTP.

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

  4. 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.

  5. Save your changes.
  6. Now, go to Setup > Email and SMS > Configure Email Server.
  7. Set the SMTP server to smtp.gmail.com, select SSL/TLS connection, and set the Port to 465.
  8. Enter the login for the Google API Console account.
  9. Do not enter a password.
  10. Enter an email address to use for a test message.
  11. Enter the default outbound email address. The outbound address does not have to be a functional email address, but it must be formatted like an email address for validation purposes. If you do plan to send emails using this address as the From address, it's best to match the email server's domain so that the emails are less likely to be marked as spam.
  12. Select the Reset checkbox at the bottom.
  13. Click Finish. This opens a page to allow you to finish the OAuth registration.
  14. Select the appropriate account.
  15. In the "Google hasn't verified this app" message, click the Continue link.
  16. Select the Read, compose, send... option and click Continue.
  17. Confirm that it shows Success, and then close the tab. Back in  Agiloft, confirm the SMTP login, empty password field, and test email address, and then click Finish.

For information on setting up inbound email with Gmail authentication, see Inbound Email Accounts.

Microsoft Office 365 OAuth 2.0 Authentication

This setup is the foundation for both inbound and outbound email using Microsoft authentication, although inbound email requires additional setup covered in Inbound Email Accounts.

This configuration relies on Device Code Flow. If you have policies that restrict the use of this, then you may run into issues. Conditional Access policies, Intune app requirements, or Company Portal app requirements may restrict use of this flow.

Getting Credentials

First, obtain OAuth 2.0 credentials from Microsoft. You'll need both an Application ID and a Tenant ID.

First, you need to register your   Agiloft system with Entra ID, formerly Azure Active Directory. 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 " Agiloft 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  Agiloft application.

With the application registered:

  1. Copy the Application ID and Tenant ID from the overview page. Store these in a note so you can copy them later.
  2. Click API Permissions in the sidebar.
  3. Expand the Microsoft Graph row and edit the delegated permissions. Delegated permissions grant access to the app as the designated email account in Agiloft.
  4. Add the following permissions:
    1. email
    2. openid
    3. offline_access
    4. profile
  5. If you have created this application solely for use with Agiloft, remove the User.Read permission.
  6. If you're configuring SMTP, also add: SMTP.Send 
  7. If you're configuring inbound email accounts, also add: IMAP.AccessAsUser.All
  8. Click Add Permissions.

  9. Click “Grant admin consent for App” to grant tenant-wide access to this app. 

    Your organization might have some policies designating how consent is granted for Apps. If you don't want to grant admin access now, your user will need to request access to the app following the App Consent policies your organization has configured.
  10. Next, go to Authentication in the sidebar.
  11. Click Add Platform and select Mobile and Desktop Applications.
  12. In the Redirect URIs, add http://localhost to the list of defaults and click Configure.
  13. Click Authentication in the sidebar again.
  14. Set "Allow public client flows" to Yes and click Save. This is required to use the device code flow.

Configuring SMTP for Microsoft

Now that you have the credentials, you can set up SMTP.

  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 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.tenant.id=**********
mail.agiloft.smtp.client.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=http://localhost
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 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 Tenant ID.

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

  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, select STARTTLS, and set the Port to 587.
  8. Enter the UserPrincipalName for the Entra account. In most cases, this is the login email address.
  9. Do not enter a password.
  10. Enter an email address to use for a test message.
  11. Enter the default outbound email address. The outbound address does not have to be a functional email address, but it must be formatted like an email address for validation purposes. If you do plan to send emails using this address as the From address, it's best to match the email server's domain so that the emails are less likely to be marked as spam.
  12. Select the Reset checkbox at the bottom.
  13. Click Finish. This shows a warning message with steps to complete the authentication. Note the code in the warning message, and then copy the URL from the warning and paste it into a new browser tab.
  14. In the page that loads, paste the code from the warning message.
  15. Click Next, log in with the Microsoft SMTP credentials that match the outbound email address, and click Continue to confirm Agiloft Email Graph sign-in.
  16. Close the tab. Back in  Agiloft, confirm the SMTP login, empty password field, and test email address, and then click Finish.

For information on setting up inbound email, see Inbound Email Accounts.

What happens if the SMTP connection fails?

By default, if the SMTP 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: