> ## 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

> Richte deinen eigenen Google OAuth-Client für Gmail ein und konfiguriere Google Cloud Pub/Sub für sofortige Gmail-Trigger

## Überblick

Mit Gmail können Agenten und Workflows E-Mails durchsuchen, lesen, entwerfen, senden und mit Labels versehen. In Langdock Cloud verbinden Nutzer Gmail über den Langdock OAuth-Client, dafür ist keine Einrichtung nötig.

Folge diesem Guide, wenn du deinen eigenen Google OAuth-Client nutzt, zum Beispiel in einem Dedicated Deployment oder um dein eigenes Branding im Zustimmungsbildschirm zu zeigen. Er hat zwei Teile:

1. [Google OAuth-Client erstellen](#google-oauth-client-erstellen), damit Nutzer Gmail verbinden können.
2. [Webhook-Trigger einrichten](#webhook-trigger-einrichten) (optional).

> [!NOTE]
>
> **Authentifizierung:** OAuth
> **Kategorie:** Kommunikation
> **Verfügbarkeit:** Alle Workspace-Pläne

## Voraussetzungen

* Ein Google Cloud-Projekt, das du verwalten kannst
* Admin-Zugriff auf deinen Langdock Workspace
* Für Webhook-Trigger: die Berechtigung, in diesem Projekt Pub/Sub-Topics, Subscriptions und Dienstkonten anzulegen

## Google OAuth-Client erstellen

**1. Gmail API aktivieren**

Wähle in der [Google Cloud Console](https://console.cloud.google.com/) dein Projekt aus, öffne **APIs & Services → Library** und aktiviere die **Gmail API**.

**2. Zustimmungsbildschirm konfigurieren**

Öffne **Google Auth Platform** und fülle **Branding** aus. Wähle unter **Audience** die Option **Internal**, wenn sich nur Nutzer deiner Google Workspace-Organisation verbinden. Gmail-Scopes sind eingeschränkt, deshalb braucht eine **External**-App eine Prüfung durch Google, bevor sich Nutzer außerhalb deiner Testnutzer verbinden können.

Füge unter **Data access** die Scopes aus [Berechtigungen](#berechtigungen) hinzu.

**3. OAuth-Client erstellen**

Öffne **Google Auth Platform → Clients** und klicke auf **Create client**. Wähle als Anwendungstyp **Web application**.

Trage unter **Authorized redirect URIs** die **Redirect-URL** aus Langdock ein. Du findest sie unter [**Workspace Einstellungen → Integrationen**](https://app.langdock.com/settings/workspace/products/integrations): Wähle **Gmail** aus und öffne unter **Bring your own OAuth Client** den Dialog für den OAuth-Client.

> [!WARNING]
>
> Die Redirect-URL muss exakt übereinstimmen. Jede Abweichung führt zu `redirect_uri_mismatch`-Fehlern bei der Authentifizierung.

Klicke auf **Create** und kopiere die **Client ID** und das **Client secret**.

**4. Client in Langdock hinzufügen**

Trage im Gmail OAuth-Client-Dialog die **Client-ID** und das **Client-Secret** ein, wähle unter **Zugriff**, wer den Client nutzen kann, klicke auf **Speichern** und bestätige. Wähle den gespeicherten Client in der Client-Liste aus und bestätige den Wechsel, um ihn zu aktivieren.

Details zu Zugriffsoptionen und Gruppen-Clients findest du unter [Bring Your Own OAuth Client](https://docs.langdock.com/de/admin/manage-integrations/bring-your-own-oauth.md).

**5. Verbindung testen**

Lass einen Nutzer sein Gmail-Konto verbinden und eine Gmail-Aktion ausführen, zum Beispiel **Search emails**.

## Webhook-Trigger einrichten

Gmail hat zwei Arten von Triggern:

* **Polling-Trigger** (**Neue E-Mail**, **Neue E-Mail entspricht Suchkriterien**, **Label an E-Mail geändert**) prüfen nach Zeitplan auf Änderungen. Sie funktionieren mit jedem OAuth-Client.
* **Webhook-Trigger** (**Monitor inbox**, **Monitor labels**, **Monitor sent emails**) starten Workflows innerhalb von Sekunden. Gmail sendet Benachrichtigungen über Änderungen per [Google Cloud Pub/Sub](https://developers.google.com/workspace/gmail/api/guides/push), deshalb braucht dein OAuth-Client ein Pub/Sub-Topic und eine Push-Subscription.

Ohne diese Einrichtung lassen sich die Webhook-Trigger nicht aktivieren. Polling-Trigger und Aktionen funktionieren weiterhin.

> [!NOTE]
>
> Das Topic muss im Google Cloud-Projekt deines OAuth-Clients liegen, und Google muss deine Langdock-Instanz erreichen können. Dedicated Deployments brauchen aktivierte Integrations-Webhook-Trigger.

**1. Cloud Pub/Sub API aktivieren**

Öffne in der Google Cloud Console das Projekt deines OAuth-Clients, gehe zu **APIs & Services → Library** und aktiviere die **Cloud Pub/Sub API**.

**2. Pub/Sub-Topic erstellen**

1. Öffne **Pub/Sub → Topics** und klicke auf **Create topic**.
2. Gib eine Topic-ID ein, zum Beispiel `gmail-webhooks`, deaktiviere **Add a default subscription** und klicke auf **Create**.
3. Klicke auf der Topic-Seite oben rechts auf **Show info panel**. Klicke im Tab **Permissions** auf **Add principal**.
4. Gib `gmail-api-push@system.gserviceaccount.com` ein, wähle die Rolle **Pub/Sub Publisher** und klicke auf **Save**.

Über dieses Konto veröffentlicht Gmail Benachrichtigungen über Änderungen in deinem Topic.

**3. Push-Dienstkonto erstellen**

1. Öffne **IAM & Admin → Service accounts** und klicke auf **Create service account**.
2. Gib einen Namen ein, zum Beispiel `gmail-pubsub-push`, und klicke auf **Create and continue**.
3. Überspringe **Permissions** und **Principals with access** und klicke auf **Done**. Das Konto braucht keine Rollen, weil Pub/Sub es nur nutzt, um die Anfragen an Langdock zu signieren.
4. Kopiere die E-Mail-Adresse des Dienstkontos aus der Liste. Du brauchst sie in den nächsten Schritten.

Damit du das Konto in der Push-Subscription auswählen kannst, brauchst du darauf die Rolle **Service Account User**. Projekt-Owner und -Editoren haben sie bereits.

**4. Topic und Dienstkonto in Langdock speichern**

1. Klappe im Gmail OAuth-Client-Dialog **Webhook-Trigger** auf.
2. Trage bei **Pub/Sub-Topic** den vollständigen Topic-Pfad ein, zum Beispiel `projects/PROJECT_ID/topics/gmail-webhooks`.
3. Trage bei **Dienstkonto der Push-Subscription** die E-Mail-Adresse des Dienstkontos ein, zum Beispiel `gmail-pubsub-push@PROJECT_ID.iam.gserviceaccount.com`.
4. Klicke auf **Speichern** und bestätige.
5. Kopiere den **Push-Endpunkt**, der jetzt im Dialog erscheint.

**5. Push-Subscription anlegen**

Öffne dein Topic unter **Pub/Sub → Topics** und klicke auf **Create subscription**:

* **Delivery type**: **Push**
* **Endpoint URL**: der Push-Endpunkt aus Langdock
* **Enable authentication**: aktiviert, mit dem Dienstkonto aus Schritt 3
* **Audience**: leer lassen
* **Retry policy**: **Retry after exponential backoff delay**
* **Expiration period**: **Never expire**

> [!WARNING]
>
> Lass **Audience** leer. Pub/Sub nutzt dann die Endpunkt-URL als Audience, und genau die prüft Langdock. Langdock lehnt Anfragen mit jeder anderen Audience ab.

Behalte die übrigen Standardwerte bei und klicke auf **Create**.

> [!NOTE]
>
> Mit der Standard-Ablaufzeit löscht Google die Subscription nach 31 Tagen ohne Benachrichtigungen, und Webhook-Trigger stoppen ohne Fehlermeldung.

**6. Webhook-Trigger testen**

Erstelle einen Workflow mit einem [Integrations-Trigger](https://docs.langdock.com/de/using-langdock/workflows/nodes/triggers/integration-trigger.md), wähle Gmail und **Monitor inbox** und sende dir selbst eine E-Mail. Der Workflow startet innerhalb von Sekunden.

### So funktioniert es

Gmail erlaubt einen Benachrichtigungskanal pro Postfach und veröffentlicht jede Änderung in deinem Topic. Eine Benachrichtigung enthält nur die Postfachadresse und eine Änderungsmarke, niemals E-Mail-Inhalte. Pub/Sub sendet sie an Langdock, signiert mit deinem Dienstkonto. Langdock prüft Signatur und Endpunkt, danach ruft jeder abonnierte Trigger die Änderungen mit seiner eigenen Gmail-Verbindung ab. Ein Trigger sieht also nur E-Mails, die seine Verbindung lesen kann.

Du brauchst nur ein Topic, ein Dienstkonto und eine Push-Subscription pro OAuth-Client. Wenn du mehrere Google OAuth-Clients hast, zeigt jeder seinen eigenen Push-Endpunkt und braucht eine eigene Push-Subscription. Liegen sie im selben Projekt, können sie sich ein Topic und ein Dienstkonto teilen.

## Berechtigungen

Füge diese Scopes zu deinem Zustimmungsbildschirm hinzu. Langdock fragt die Scopes an, die die in deinem Workspace aktivierten Aktionen brauchen. Mehr dazu unter [Action-Level-Scopes verwalten](https://docs.langdock.com/de/admin/manage-integrations/manage-action-level-scopes.md).

| Scope | Verwendet für |
| - | - |
| `https://www.googleapis.com/auth/gmail.readonly` | Verbinden, alle Trigger, E-Mails lesen und durchsuchen, Labels auflisten |
| `https://www.googleapis.com/auth/gmail.send` | E-Mails senden, beantworten und weiterleiten |
| `https://www.googleapis.com/auth/gmail.compose` | Entwürfe erstellen und aktualisieren |
| `https://www.googleapis.com/auth/gmail.modify` | Labels hinzufügen und entfernen |
| `https://www.googleapis.com/auth/gmail.labels` | Labels erstellen |

## Fehlerbehebung

> [accordion] Ein Webhook-Trigger lässt sich nicht aktivieren
>
> Prüfe, ob im Abschnitt **Webhook-Trigger** des OAuth-Clients sowohl das Topic als auch das Dienstkonto eingetragen sind und ob die Verbindung mit diesem OAuth-Client erstellt wurde. Verbindungen bleiben mit dem Client verknüpft, mit dem sie erstellt wurden.
>
> Prüfe außerdem, ob das Topic im selben Google Cloud-Projekt liegt wie der OAuth-Client und ob `gmail-api-push@system.gserviceaccount.com` darauf die Rolle **Pub/Sub Publisher** hat.

> [accordion] Der Trigger ist aktiv, aber Workflows starten nie
>
> Öffne die Push-Subscription in der Google Cloud Console und prüfe die Antwortcodes unter **Metrics → Push**:
>
> * `401`: Die Subscription hat die Authentifizierung deaktiviert, nutzt ein anderes Dienstkonto als das in Langdock gespeicherte oder hat eine **Audience** gesetzt.
> * `403`: Eine Firewall, eine WAF oder ein Proxy vor Langdock blockiert die Anfragen von Google. Erlaube `POST`-Anfragen an `/api/webhook-pubsub/`. Langdock prüft die Signatur jeder Anfrage selbst.
> * `404`: Die Endpunkt-URL stimmt nicht mit dem Push-Endpunkt in Langdock überein, oder der OAuth-Client hat keine Webhook-Trigger-Einstellungen.


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