# 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:
# Minimum and default scopes
At a minimum, the See your primary Google Account email address scope is required to establish a connection.
If no scopes are specified, Workato requests the following by default:
- See your primary Google Account email address
- See and edit your email labels
- Send email on your behalf
- View your email messages and settings
- Read, compose, and send emails from your Gmail account
If connecting with a service account, ensure your Google Workspace Admin grants domain-wide authority delegation (opens new window) to the service account. This allows it to impersonate the user email entered during connection setup, with the necessary scopes and permissions.
# OAuth 2.0 authentication
ADD WORKATO TO THE ALLOWLIST
The New email trigger and Download attachment action 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 configure specific OAuth 2.0 scopes before you link your account if you plan to use the New email trigger or Download attachment action. Refer to Add Workato Gmail connector to the allowlist for more information.
Complete the following steps to set up an OAuth 2.0 connection:
Sign in to your Workato account and navigate to the project where you plan to add your Gmail connection.
Click Create > Connection, then select Gmail as your connection.
Provide a Connection name that uniquely identifies the Gmail connection instance.
Click the Authentication type menu and select OAuth 2.0.
Optional. Click Advanced settings and select additional OAuth 2.0 scopes. If left blank, the following scopes are requested:
- See your primary Google Account email address
- See and edit your email labels
- Send email on your behalf
- View your email messages and settings
- Read, compose, and send emails from your Gmail account
Click Sign in with Google and sign in to your Google account to complete the setup.
# Service account authentication
You can also authenticate to Gmail using a Google Cloud service account. A service account is a special type of Google account associated with your Google Cloud Project that can be used to run API requests on your behalf. You can use a service account in Gmail to ensure that the solution continues running even if an individual user's permissions change. Refer to the Google documentation on service accounts (opens new window) for more information.
You must sign in to your Google Cloud Platform (GCP) console to create a service account. Refer to the Google Cloud documentation to learn how to achieve the following:
- Create a new service account (opens new window) in your GCP project.
- Create a new private key and download the key in JSON format (opens new window).
After you download the key file, you can't download it again.
Obtain a GCP Project service account email
Complete the following steps to set up a service account connection:
Sign in to your Workato account and navigate to the project where you plan to add your Gmail connection.
Click Create > Connection, then select Gmail as your connection.
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 service account's email address. |
| 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. |
Click Sign in with Google and sign in to your Google account to complete the setup.
SERVICE ACCOUNT USER IMPERSONATION
The service account impersonates the user email entered during connection setup after authentication is complete.
# Add Workato Gmail connector to the allowlist
Refer to the Google Workspace Admin documentation for detailed instructions on managing OAuth-based access to connected apps (opens new window).
Complete the following steps to add the Workato Gmail connector app to the allowlist:
SUPER ADMINISTRATOR ROLE REQUIRED
You must be signed in as a super administrator (opens new window) of your Google Workspace to complete the following actions.
Sign in to the Admin Console of your Google Workspace.
Navigate to Security > API controls.
Click Security in Admin Console
Click API controls
Navigate to Manage third-party app access and click Add app > OAuth App Name Or Client ID.
Click Manage third-party app access
Click Add app > OAuth App Name Or Client ID
Search for the Workato Gmail connector app by its OAuth 2.0 client ID:
763335457294-gp4359qrjgu7vl96eit0p2n725197oki.apps.googleusercontent.com
Click Select on the available OAuth client ID.
Fill in the OAuth 2.0 Client ID
Check the box for the client ID you plan to configure, then click Select.
Select the available OAuth client ID
Select the user you plan to configure access for.
Select the user to configure access for
Click Continue.
Select the Trusted option for app access.
Select trust level for the Workato app
Click Continue.
Review the settings for the new app, then click Finish.
Review settings for the new app, then click Finish
Navigate to Workato to finish configuring your Gmail connection.
Click Sign in with Google and sign in to your Google account to complete the setup.
Last updated: 9/13/2024, 2:23:00 AM