# 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

Complete the following steps to set up an OAuth 2.0 connection:

1

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

2

Click Create > Connection, then select Gmail as your connection.

3

Provide a Connection name that uniquely identifies the Gmail connection instance.

4

Click the Authentication type menu and select OAuth 2.0.

5

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
6

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:

After you download the key file, you can't download it again.

Getting GCP Project service account emailObtain a GCP Project service account email

Complete the following steps to set up a service account connection:

1

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

2

Click Create > Connection, then 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 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.
4

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.


Last updated: 3/27/2025, 4:18:44 PM