Email Setup with Gmail OAuth 2.0
Agiloft can be configured to access Gmail mailboxes using the Gmail API with OAuth 2.0 protocol. 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, properties, and variables in Agiloft include "smtp" in the name, the instructions below configure Agiloft to access Gmail with OAuth 2.0. Agiloft does not use SMTP authentication.
Prerequisites
Before setting up email in Agiloft, review the following list of requirements and recommendations:
- To use Agiloft with Gmail OAuth 2.0, you need to authorize Agiloft as a Google Web Server Application. Other authorization types are not supported. The steps in Add Agiloft as an OAuth Client are an example of how to authorize Agiloft as a web application.
- You need admin access to your Google Workspace and Google Cloud Console.
- We recommend you create at least one separate Gmail 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.
- You need the credentials for these accounts to complete the OAuth registration when you set up email in Agiloft.
- Since Agiloft acts as an email client and reads messages from the specified inbound mailboxes, IMAP must be enabled for your inbound Gmail accounts. Once Agiloft is added as an OAuth client, you can enable IMAP based on Client ID. See the Google Workspace Admin Help for details. For more information on how Agiloft checks inbound email, see Inbound Email Processing.
When you're ready to get started, proceed with adding Agiloft as an OAuth client.
Add Agiloft as an OAuth Client
The steps below provide general guidance on adding Agiloft as an OAuth 2.0 client.
- Log into the Google Cloud Platform Console as an administrator and go to APIs & Services.
- Create a new project:
- At the top of the screen, click the current project name to open the Select a resource dialog box.
- In the dialog box, click New project.
- Enter a project name, such as Agiloft Email, and change the Organization and Location if needed.
- Click Create. The new project is selected at the top of the screen.
- Next, enable the Gmail API in the project:
- At the top of the Enabled APIs & services screen, click Enable APIs and Services.
- In the API Library, search for and select the Gmail API, then click Enable. The API/Service Details for the API is displayed.
- Next, create the consent screen for the new project. For information on consent screens, refer to Google's documentation on setting up consent screens.
- In the left sidebar, click OAuth consent screen, then click Get Started to configure the project.
- Under App information, enter the name of the application, such as Agiloft.
- In User support email, select the email address where users can get support, then click Next.
- Under Audience, select Internal to limit access to the app to users within your organization, then click Next.
- Under Contact information, enter the email address where Google should send project notifications, then click Next.
- Agree to the Google API Services User Data policy and click Continue.
- Click Create. The OAuth Overview is displayed.
- Next, click Branding in the sidebar. For information on branding, refer to Google's documentation on managing OAuth app branding.
- For the App domain settings, you can enter the following URLs for Agiloft's home page, privacy policy, and terms of service:
- For Authorized Domains, add each applicable domain:
- Add your company domain.
- If your KB is in the Agiloft domain or you included Agiloft URLs in App domains, add
agiloft.com
. - If the domain for your KB is not
agiloft.com
or your company's domain, also add the KB domain.
- Click Save to save the changes.
- Next, create the Agiloft web client:
- Click Clients in the sidebar, then click Create Client at the top of the screen.
- For Application type, select Web application.
- Enter a Name for the client, such as Agiloft Email Client.
- Leave Authorized JavaScript origins blank.
- Under Authorized redirect URIs, click Add URI and enter the following URI:
https://DOMAIN_NAME/ui/emailoauth2
. Replace DOMAIN_NAME with the domain for your KB. For example:https://example.agiloft.com/ui/emailoauth2
. - Click Create.
- Once the client is created, copy the Client ID to a note so you can refer to it later in the setup. In addition, view the client details and copy the Client secret value to the note.
- Now, configure the required Data Access settings:
- Click Data Access in the sidebar, then click Add or remove scopes.
- Under Manually add scopes, enter:
https://mail.google.com
- Click Add to Table.
- Now, in the table, select the
mail.google.com
,userinfo.email
,userinfo.profile
, andopenid
scopes. - Click Update at the bottom of the screen, then click Save on the Data Access screen.
- Complete any other optional client configuration as needed.
Now that the Agiloft OAuth client is created, you can set up outbound email in Agiloft.
Set Up Outbound Email
Follow the steps below to set up the default outbound account in Agiloft. You need the Client ID and Client secret you copied when adding the OAuth client. You also need the credentials for the outbound account so you can sign in with Google and complete the OAuth registration.
- Go to Setup > System > Manage Global Variables.
- 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.
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.client.id=CLIENT_ID mail.agiloft.smtp.tenant.id=CLIENT_SECRET # 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
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 Client ID.CLIENT_SECRET
- Replace CLIENT_SECRET with your Client secret.
- Click Finish to save your changes.
- Now, go to Setup > Email and SMS > Configure Email Server.
- Set the SMTP server to:
smtp.gmail.com
- Select SSL/TLS connection and set the Port to 465.
- For SMTP login, enter the email address for outbound account.
- Do not enter a password.
- In Default outbound email address, enter the address for the outbound account again. The system will send all outgoing messages from this address.
- Select the Reset checkbox at the bottom of the screen.
- Click Finish. This opens a page that prompts you to finish the OAuth registration.
- Click the link to finish the OAuth registration and follow the steps to sign in with Google as the user for the outbound email address. Make sure you sign in as the outbound account user, not the Google Cloud admin
- Confirm that the browser shows a Success message, then close the tab.
- Back in Agiloft, click the link to finish the wizard, then click Configure Email Server.
- Enter an email address to send a test message to.
- 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.
You need the Client ID and Client secret you copied when creating the OAuth client. You also need the credentials for the inbound account so you can sign in with Google and complete the OAuth registration.
- First, make sure IMAP is enabled for the inbound Gmail account. See the Google Workspace Admin Help for instructions.
- Go to Setup > Email and SMS > Configure Inbound Email. This list includes all existing inbound email accounts for all tables.
- Edit the demo configuration for Contract. If you've already configured Contract and are adding another inbound account, select a different demo configuration to modify or click New to create a new configuration.
- On the Table tab, if the table isn't already selected because this is a new configuration, select the table to add the inbound account to. If you're editing an existing configuration, the table is already selected.
- Click Next.
- On the Server tab, select IMAP and enter:
imap.gmail.com
- Select SSL/TLS connection and set the Custom Port to 993.
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=manual mail.agiloft.inbound.client.id=CLIENT_ID mail.agiloft.inbound.tenant.id=CLIENT_SECRET # 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
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 client ID.CLIENT_SECRET
- Replace CLIENT_SECRET with your client secret.
Click Next.
On the Account tab, click the finish OAuth registration link that appears above the "Status: Communication established with imap.gmail.com" message.
- Follow the steps to sign in with Google as the user for the inbound email address. Make sure you sign in as the inbound account user, not the Google Cloud admin.
- Confirm that the browser shows a Success message, then close the tab.
- Back in Agiloft on the Account tab, enter the full inbound email address in the Email and Email Account fields.
- Leave the Password field empty. If a series of dots has replaced a previously blank password, delete them.
- 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 Gmail account still receives messages, but Agiloft won't access them to pull them into the system.
- If incoming messages are saved to a folder other than Inbox, enter the folder path where Agiloft should check for incoming emails.
- Click Next and confirm that a message appears stating the account is valid. If you see an error message, retrace your steps and check your work.
- 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: