Gmail

Gmail (opens new window) is a popular email service used by both consumers and businesses alike. Users can access Gmail on the web and using third-party programs that synchronize email content through POP or IMAP protocols.

The Gmail connector enables you to build powerful automation around Gmail and connect with other applications.

API version

The Gmail connector uses the Gmail REST API v1 (opens new window).

How to connect to Gmail on Workato

Workato supports two types of connections to Gmail:

• OAuth 2.0 authentication
• Service account authentication

Minimum scopes required to connect

The Gmail connector requires the following minimum scopes:

• See your primary Google Account email address
• See and edit your email labels
• Send email on your behalf

You must ask your Google Workspace Admin to grant the service account domain-wide authority delegation (opens new window) with the necessary scopes and permissions to impersonate the user email entered during connection setup if you plan to connect with a service account.

OAuth 2.0 authentication

ADD WORKATO TO THE ALLOWLIST

Gmail triggers or download attachment actions can only be used by paid Google Workspace accounts in compliance with Google's updated security policies. You must add Workato's Gmail connector app to the allowlist and grant it read permissions before you link your account, if you plan to use the Gmail New email trigger or Download attachment action. Learn more.

1

Log in to your Workato account and navigate to the project where you plan to add your Gmail connection.

2

Click Create > Connection > select Gmail as your connection.

3

Click Advanced settings and select the OAuth 2.0 option from the Authentication type drop-down menu and enter the following information:

Connection field	Description
Connection name	Give this connection a unique name that identifies the Gmail connection instance.
OAuth 2.0 scopes	Select additional OAuth 2.0 scopes to request for this connection. When left blank, a default set of scopes is requested.

4

Click Sign in with Google and log in to your Google account to complete setup.

Service account authentication

You can authenticate to Gmail using a Google Cloud service account. A service account is a special type of Google account that is associated with your Google Cloud Project that Workato can use to run API requests on your behalf. Service accounts can be used in Gmail to ensure that the solution continues to run even if individual users' permissions change. Read more about service accounts here (opens new window).

You must to log in to your Google Cloud Platform (GCP) console to create a service account. Follow the guide here (opens new window) to create a new service account in your GCP project. Follow this guide (opens new window) to add a new private key and download the key in JSON format. Note that after you download the key file, you cannot download it again.

Obtain a GCP Project service account email

1

Log in to your Workato account and navigate to the project where you plan to add your Gmail connection.

2

Click Create > Connection > select Gmail as your connection.

3

Select the Service account option from the Authentication type drop-down menu and enter the following information:

Connection field	Description
Connection name	Give this connection a unique name that identifies the Gmail connection instance.
GCP project service account email	Provide the email address of the service account.
Private key	Copy and paste the private key obtained from the downloadable JSON. Include both the -----BEGIN PRIVATE KEY----- to -----END PRIVATE KEY-----\n
User email	Provide the email address of the user account to impersonate. Workato performs actions on behalf of the impersonated email through the authenticated service account.
OAuth 2.0 scopes	Select additional OAuth 2.0 scopes to request for this connection. When left blank, a default set of scopes is requested.

TIP

Once authenticated, the service account impersonates the user email entered during connection setup.

Add Workato Gmail connector to the allowlist

Follow (opens new window) Google’s detailed instructions for managing OAuth-based access to connected apps. Refer to the following step-by-step guide for adding the Workato Gmail Connector app for your Google Workspace account to the allowlist.

1

Login to the Admin Console of your Google Workspace.

You must be signed in as a super administrator (opens new window) of your Google Workspace to complete the following actions.

Login to Admin Console of your Google Workspace

2

Navigate to the API controls in Security Settings by going to Security > API Controls. This might be located at the bottom of the page.

API Controls

3

Navigate to Manage third-party app access and select Configure new app and OAuth App Name Or Client ID from the drop-down.

Select trusted apps

Configure new app

4

Fill in the OAuth 2.0 Client ID for the Workato Gmail Connector.

763335457294-gp4359qrjgu7vl96eit0p2n725197oki.apps.googleusercontent.com

5

Select the available OAuth client ID.

Fill in the OAuth 2.0 Client ID

6

Select the available OAuth client ID.

Select the available OAuth client ID

7

Select the Trusted option for app access.

Select trust level for the Workato app

8

Lastly, set Read email permission to Yes and select Link your account.

Select Yes for read email permission