> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gmail

> Set up your own Google OAuth client for Gmail and configure Google Cloud Pub/Sub for instant Gmail triggers

## Overview

Gmail lets agents and workflows search, read, draft, send, and label emails. On Langdock Cloud, members can connect Gmail with the Langdock OAuth client, and no setup is needed.

Follow this guide if you use your own Google OAuth client, for example on a dedicated deployment or to show your own branding on the consent screen. It has two parts:

1. [Create a Google OAuth client](#create-a-google-oauth-client) so members can connect Gmail.
2. [Set up webhook triggers](#set-up-webhook-triggers) (optional).

> [!NOTE]
>
> **Authentication:** OAuth
> **Category:** Communication
> **Availability:** All workspace plans

## Prerequisites

* A Google Cloud project you can manage
* Admin access to your Langdock workspace
* For webhook triggers: permission to create Pub/Sub topics, subscriptions, and service accounts in that project

## Create a Google OAuth client

**1. Enable the Gmail API**

In the [Google Cloud console](https://console.cloud.google.com/), select your project, open **APIs & Services → Library**, and enable the **Gmail API**.

**2. Configure the consent screen**

Open **Google Auth Platform** and complete **Branding**. Under **Audience**, choose **Internal** if only users of your Google Workspace organization connect. Gmail scopes are restricted, so an **External** app needs Google's verification before users outside your test users can connect.

Under **Data access**, add the scopes listed in [Permissions](#permissions).

**3. Create the OAuth client**

Open **Google Auth Platform → Clients** and click **Create client**. Choose **Web application** as the application type.

Under **Authorized redirect URIs**, add the **Redirect URL** from Langdock. To find it, go to [**Workspace settings → Integrations**](https://app.langdock.com/settings/workspace/products/integrations), select **Gmail**, and open the OAuth client dialog under **Bring your own OAuth Client**.

> [!WARNING]
>
> The redirect URL must match exactly. Any mismatch causes `redirect_uri_mismatch` errors during authentication.

Click **Create** and copy the **Client ID** and **Client secret**.

**4. Add the client in Langdock**

In the Gmail OAuth client dialog, enter the **Client ID** and **Client secret**, choose who can use the client under **Access**, then click **Save** and confirm. Select the saved client from the client list and confirm the switch to activate it.

For details on access options and group clients, see [Bring Your Own OAuth Client](https://docs.langdock.com/en/admin/manage-integrations/bring-your-own-oauth.md).

**5. Test the connection**

Have a user connect their Gmail account and run a Gmail action, such as **Search emails**.

## Set up webhook triggers

Gmail has two kinds of triggers:

* **Polling triggers** (**New email**, **New email matching search**, **Label changed on email**) check for changes on a schedule. They work with any OAuth client.
* **Webhook triggers** (**Monitor inbox**, **Monitor labels**, **Monitor sent emails**) start workflows within seconds. Gmail sends change notifications through [Google Cloud Pub/Sub](https://developers.google.com/workspace/gmail/api/guides/push), so your OAuth client needs a Pub/Sub topic and push subscription.

Without this setup, the webhook triggers fail to turn on. Polling triggers and actions keep working.

> [!NOTE]
>
> The topic must be in your OAuth client's Google Cloud project, and Google must be able to reach your Langdock instance. Dedicated deployments need integration webhook triggers enabled.

**1. Enable the Cloud Pub/Sub API**

In the Google Cloud console, open the project of your OAuth client, go to **APIs & Services → Library**, and enable the **Cloud Pub/Sub API**.

**2. Create a Pub/Sub topic**

1. Open **Pub/Sub → Topics** and click **Create topic**.
2. Enter a topic ID, such as `gmail-webhooks`, clear **Add a default subscription**, and click **Create**.
3. On the topic page, click **Show info panel** in the top right. In the **Permissions** tab, click **Add principal**.
4. Enter `gmail-api-push@system.gserviceaccount.com`, select the **Pub/Sub Publisher** role, and click **Save**.

Gmail uses this account to publish change notifications to your topic.

**3. Create a push service account**

1. Open **IAM & Admin → Service accounts** and click **Create service account**.
2. Enter a name, such as `gmail-pubsub-push`, and click **Create and continue**.
3. Skip **Permissions** and **Principals with access** and click **Done**. The account needs no roles, because Pub/Sub only uses it to sign the requests it sends to Langdock.
4. Copy the service account email from the list. You need it in the next steps.

To select this account in the push subscription, you need the **Service Account User** role on it. Project owners and editors already have it.

**4. Save the topic and service account in Langdock**

1. In the Gmail OAuth client dialog, expand **Webhook triggers**.
2. In **Pub/Sub topic**, enter the full topic path, such as `projects/PROJECT_ID/topics/gmail-webhooks`.
3. In **Push subscription service account**, enter the service account email, such as `gmail-pubsub-push@PROJECT_ID.iam.gserviceaccount.com`.
4. Click **Save** and confirm.
5. Copy the **push endpoint** that now appears in the dialog.

**5. Create a push subscription**

Open your topic in **Pub/Sub → Topics** and click **Create subscription**:

* **Delivery type**: **Push**
* **Endpoint URL**: the push endpoint from Langdock
* **Enable authentication**: on, with the service account from step 3
* **Audience**: leave empty
* **Retry policy**: **Retry after exponential backoff delay**
* **Expiration period**: **Never expire**

> [!WARNING]
>
> Leave **Audience** empty. Pub/Sub then uses the endpoint URL as the audience, which is what Langdock checks. Langdock rejects requests with any other audience.

Keep the other defaults and click **Create**.

> [!NOTE]
>
> With the default expiration, Google deletes the subscription after 31 days without notifications, and webhook triggers stop without an error.

**6. Test a webhook trigger**

Create a workflow with an [Integration Trigger](https://docs.langdock.com/en/using-langdock/workflows/nodes/triggers/integration-trigger.md), choose Gmail and **Monitor inbox**, and send yourself an email. The workflow starts within seconds.

### How it works

Gmail allows one notification channel per mailbox and publishes every change to your topic. A notification only contains the mailbox address and a change marker, never email content. Pub/Sub pushes it to Langdock, signed by your service account. Langdock checks the signature and endpoint, then each subscribed trigger fetches the changes with its own Gmail connection. A trigger only ever sees emails that its connection can read.

You only need one topic, service account, and push subscription per OAuth client. If you have several Google OAuth clients, each one shows its own push endpoint and needs its own push subscription, but they can share one topic and service account if they are in the same project.

## Permissions

Add these scopes to your consent screen. Langdock requests the scopes needed by the actions enabled in your workspace. Learn more in [Manage Action-Level Scopes](https://docs.langdock.com/en/admin/manage-integrations/manage-action-level-scopes.md).

| Scope | Used for |
| - | - |
| `https://www.googleapis.com/auth/gmail.readonly` | Connecting, all triggers, reading and searching emails, listing labels |
| `https://www.googleapis.com/auth/gmail.send` | Sending, replying to, and forwarding emails |
| `https://www.googleapis.com/auth/gmail.compose` | Creating and updating drafts |
| `https://www.googleapis.com/auth/gmail.modify` | Adding and removing labels |
| `https://www.googleapis.com/auth/gmail.labels` | Creating labels |

## Troubleshooting

> [accordion] A webhook trigger fails to turn on
>
> Check that the **Webhook triggers** section of the OAuth client has both the topic and the service account, and that the connection was created with that OAuth client. Connections keep the client they were created with.
>
> Also check that the topic is in the same Google Cloud project as the OAuth client and that `gmail-api-push@system.gserviceaccount.com` has the **Pub/Sub Publisher** role on it.

> [accordion] The trigger turns on but workflows never start
>
> Open the push subscription in the Google Cloud console and check the response codes under **Metrics → Push**:
>
> * `401`: the subscription has authentication turned off, uses a different service account than the one saved in Langdock, or has an **Audience** set.
> * `403`: a firewall, WAF, or proxy in front of Langdock blocks Google's requests. Allow `POST` requests to `/api/webhook-pubsub/`. Langdock verifies each request's signature itself.
> * `404`: the endpoint URL does not match the push endpoint shown in Langdock, or the OAuth client has no webhook trigger settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.