Gmail is Google's email service for sending, receiving and organizing mail, with labels, threads, search and attachments. The UnifyApps Gmail connector uses the Gmail API to send, forward and draft emails, read messages and threads, manage labels, download attachments and react to new mail from workflows and agents.
This guide covers every authentication type available on the connection form, and the actions and triggers supported, along with the Gmail scope each one needs.
Authentication
Before you begin, you should have the following information:
Connection name: a descriptive name such as MyAppGmailIntegration, so the connection is easy to identify later.
Authentication type: select the type of authentication for connecting to your Gmail account:
OAuth
OAuth with Client Credentials
Service Account
Every authentication type has a Scopes field. It defaults to https://mail.google.com/ (full mailbox access), which covers every action below. Choose narrower scopes only if you know which actions the connection will run; see the Scopes Required column in the tables below.
1. OAuth
Use this when you want to connect with your own Google account and do not need to create a Google Cloud app.
Enter a Connection name.
Select OAuth as the Authentication type.
Keep the default Scopes, or select the scopes you need.
Click Authorize. You are redirected to the Google sign-in page.
Sign in with the Google account whose mailbox the connection should use.
Review the permissions on the consent screen, for example Read, compose, send, and permanently delete all your email from Gmail, and click Allow.
You are redirected back to UnifyApps with a confirmation that the account is connected.


2. OAuth with Client Credentials
Use this when your organization wants the connection to use its own Google Cloud OAuth client, while actions still run as the Google user who signs in.
Step 1: Create an OAuth client in Google Cloud
In the Google Cloud Console, select or create a project, and enable the Gmail API under APIs & Services → Library.
Go to Google Auth platform → Branding. If you see Google Auth platform not configured yet, click Get Started, enter an App name, User support email, Audience and contact email, and click Create.
Go to Data Access, click Add or Remove Scopes, select the Gmail scopes the connection will use, and click Save. If the audience is External, add the users who will sign in under Audience → Test users.
Go to Google Auth platform → Clients and click Create Client. Choose Web application as the Application type and enter a name.
Under Authorized redirect URIs, click Add URI and paste the Callback URL shown on the UnifyApps connection form (it is copyable and differs per environment).
Click Create, then copy the Client ID and Client secret. Copy the secret immediately: Google shows it only once.
Step 2: Connection setup in UnifyApps
Open Connections → New Connection → Gmail and enter a Connection name.
Select OAuth with Client Credentials as the Authentication type.
Enter the Client ID and Client Secret copied from Google Cloud.
Select the same Scopes you added to the consent screen.
Click Authorize, sign in with Google and click Allow on the consent screen.
Confirm the success message after the redirect back to UnifyApps.
3. Service Account
Use this for Google Workspace domains, where a service account acts on behalf of a user in the domain through domain-wide delegation. No user has to sign in.
Step 1: Create a service account in Google Cloud
In the Google Cloud Console, select or create a project, and enable the Gmail API under APIs & Services → Library.
Go to IAM & Admin → Service Accounts and click Create service account. Enter a name and click Done.
Open the service account and copy its Email. Click Show advanced settings and, under Domain-wide delegation, copy the Client ID used in the next step.
Go to the Keys tab → Add key → Create new key, choose JSON and click Create. The downloaded file holds the
client_emailandprivate_key. Store it securely.


Step 2: Give the service account domain-wide access
A Google Workspace super administrator opens the Admin console → Security → Access and data control → API controls.
Click Manage Domain Wide Delegation → Add new.
Enter the service account's client ID, add the OAuth scopes the connection will use (for example
https://mail.google.com/), separated by commas, and click Authorize. See Delegate domain-wide authority to your service account for details.
Note: the connection can only reach the mailboxes of users in the Workspace domain where domain-wide delegation was granted, and the scopes you select in UnifyApps must also be granted here. Google says changes can take up to 24 hours to apply.
Step 3: Create the connection in UnifyApps
Select Service Account as the Authentication type.
Enter the GCP Project Service Account Email and paste the Private Key from the JSON key file.
Enter the User Email of the Workspace user whose mailbox the connection acts on.
Select the Scopes granted in Step 2.
Click Test Connection to validate the credentials, then click Create.
Actions
Scopes are shown in short form: gmail.modify means https://www.googleapis.com/auth/gmail.modify. Any broader scope also works; https://mail.google.com/ covers every action. Search-based actions and triggers do not work with gmail.metadata alone, because Google does not allow search queries with that scope.
Actions | Description | Scopes Required |
|---|---|---|
| Adds labels to a message in Gmail. | gmail.modify |
| Adds labels to multiple messages. | gmail.modify |
| Permanently deletes several emails at once. They cannot be recovered. | https://mail.google.com/ |
| Creates a draft email in Gmail. | gmail.compose (plus gmail.modify if you add labels) |
| Creates a draft reply to an email in Gmail. | gmail.compose (plus gmail.modify if you add labels) |
| Creates a label in Gmail. | gmail.labels (or gmail.modify) |
| Moves the specified email to the trash in Gmail. | gmail.modify |
| Permanently deletes an email, skipping the trash. It cannot be recovered. | https://mail.google.com/ |
| Retrieves attachments from a specific email in Gmail. | gmail.readonly (or gmail.modify) |
| Searches for emails in Gmail, and can send a new email when none is found. | gmail.readonly (or gmail.modify); plus gmail.send to send when none is found |
| Forwards an email in Gmail. | gmail.readonly and gmail.send (or gmail.modify, which also covers adding labels) |
| Returns the mailbox's current history ID, to pass to List mailbox history later and pick up every change from that point on. | gmail.readonly (or gmail.metadata) |
| Gets a message from Gmail. | gmail.readonly (or gmail.modify) |
| Gets specific details of a message from Gmail. | gmail.readonly (or gmail.modify) |
| Gets a specific thread from Gmail. | gmail.readonly (or gmail.modify) |
| Lists the emails received in Gmail. | gmail.readonly (or gmail.modify) |
| Lists the history of changes to the mailbox of the connected user. | gmail.readonly (or gmail.metadata) |
| Lists the signatures set up in Gmail. | gmail.readonly (or gmail.settings.basic) |
| Lists the threads in the mailbox of the connected user. | gmail.readonly (or gmail.modify) |
| Removes labels from a message in Gmail. | gmail.modify |
| Removes labels from multiple messages in Gmail. | gmail.modify |
| Replies in a thread in Gmail. | gmail.send (or gmail.compose) |
| Resolves an RFC 2822 Message-ID (the trigger's rfc822MessageId) to the Gmail message ID that Get message needs. | gmail.readonly (or gmail.modify) |
| Sends an email in Gmail. | gmail.send (plus gmail.modify if you add labels) |
| Starts a watch that sends real-time notifications to a Google Cloud Pub/Sub topic. | gmail.readonly (or gmail.metadata) |
Triggers
Triggers | Description | Scopes Required |
|---|---|---|
| Triggers when a new email is received in Gmail. | gmail.readonly (or gmail.modify) |
| Triggers in real time through Google Cloud Pub/Sub when the mailbox changes, for example when a new email is received. | gmail.readonly and pubsub |
| Triggers when a new email with an attachment is received in Gmail. | gmail.readonly (or gmail.modify) |
| Triggers when a new email matching the given search query is received. | gmail.readonly (or gmail.modify) |
| Triggers when a new thread starts in Gmail. | gmail.readonly (or gmail.modify) |
| Triggers when a new reply is received in an existing email thread in Gmail. | gmail.readonly (or gmail.modify) |
| Triggers when an email is starred in Gmail. | gmail.readonly (or gmail.modify) |
| Triggers when an email is moved to the trash in Gmail. | gmail.readonly (or gmail.modify) |