dify-plugin-sdks/python/examples/gmail_trigger/README.md

Gmail Trigger (Push + History)

Overview
- Gmail Trigger is a Dify provider that receives Gmail push notifications via Cloud Pub/Sub and emits concrete events based on Gmail History:
  - `gmail_message_added` (new messages)
  - `gmail_message_deleted` (deleted messages)
  - `gmail_label_added` (labels added to messages)
  - `gmail_label_removed` (labels removed from messages)
- Dispatch verifies/auths the push, pulls the history delta once, and splits changes for events to consume.
- Note: API Key is NOT supported for Gmail API access. Use OAuth (gmail.readonly) only.

Prerequisites
- A Google account authorized for Gmail API (used during OAuth)
- A Google Cloud project with Pub/Sub enabled (manual setup)

Step-by-step Setup
1) Install the plugin in Dify
- Options:
  - If packaged as `.difypkg`, import it in Dify’s Plugin Center (Plugins → Import).
  - For local run during development, ensure the runtime installs dependencies in `requirements.txt`.

2) Configure OAuth in the provider (one-time)
- In Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth client ID
  - Application type: Web application
  - Authorized redirect URIs: Copy the redirect URI shown by Dify when setting up OAuth for this provider
- Back in Dify, enter Client ID/Secret; click “Authorize” to complete OAuth (gmail.readonly)
- The constructor validates the token via `users/me/profile`

3) Create a Gmail subscription in Dify
- Parameters
  - `watch_email` (userId): use `me` or the full Gmail address
  - `topic_name`: Paste the full Pub/Sub topic path you created (e.g., `projects/<PROJECT_ID>/topics/<TOPIC>`). If you configure tenant-level GCP client params (see below), you may leave this empty and the plugin will auto-provision Pub/Sub.
  - `label_ids` (optional): scope to specific labels (INBOX/UNREAD...)
    - Docs: https://developers.google.com/gmail/api/reference/rest/v1/users.labels/list
  - `label_filter_action` (optional): `include` or `exclude` for users.watch
    - Docs: https://developers.google.com/gmail/api/reference/rest/v1/users/watch#request-body
  - Properties (optional)
    - `require_oidc`: enforce OIDC bearer verification
    - `oidc_audience`: use the exact webhook endpoint URL (shown after subscription is created)
    - `oidc_service_account_email`: the service account used by the Pub/Sub push subscription
- After you click Create, open the subscription details and copy the Webhook Endpoint URL. You will use this in Pub/Sub push.

4) Prepare Pub/Sub (manual)
   - Enable APIs:
     - Gmail API: https://console.cloud.google.com/apis/library/gmail.googleapis.com
     - Cloud Pub/Sub API: https://console.cloud.google.com/apis/library/pubsub.googleapis.com
   - Create topic:
     - `gcloud pubsub topics create <TOPIC> --project=<PROJECT_ID>`
   - Grant Gmail publisher on the topic:
     - `gcloud pubsub topics add-iam-policy-binding projects/<PROJECT_ID>/topics/<TOPIC> \
        --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
        --role=roles/pubsub.publisher`
   - Create a Push subscription to the Callback URL displayed by Dify:
     - `gcloud pubsub subscriptions create <SUB_NAME> \
        --topic=projects/<PROJECT_ID>/topics/<TOPIC> \
        --push-endpoint="https://<YOUR_DIFY_HOST>/api/plugin/triggers/<SUBSCRIPTION_ID>"`
     - OIDC (optional): add `--push-auth-service-account=<YOUR_SA_EMAIL>` and `--push-auth-token-audience="<Callback URL>"`

Auto mode (tenant-level)
- Configure in OAuth client params (one-time, tenant-level):
  - `gcp_project_id`: GCP project ID
  - `gcp_service_account_json`: Service Account JSON with Pub/Sub admin perms
  - Optional `gcp_topic_id`: default to `dify-gmail`
- With these set, if `topic_name` is empty, the plugin will:
  - Create/reuse Topic and grant Gmail publisher
  - Create a dedicated Push subscription per Dify subscription (supports OIDC)
  - Call `users.watch` with the managed Topic
- On unsubscribe, the plugin will best-effort delete the managed Push subscription (Topic is preserved for reuse).

Where To Get OIDC Values
- `oidc_audience`
  - Use the exact webhook endpoint URL shown in the Dify subscription details (Endpoint). Example:
    - `https://<your-dify-host>/api/plugin/triggers/<subscription-id>`
  - The YAML field includes a URL to Google docs for the `audience` claim: see the OIDC token reference.
- `oidc_service_account_email`
  - The service account used by the Pub/Sub push subscription (set via `--push-auth-service-account`).
  - Find it under Google Cloud Console → IAM & Admin → Service Accounts, or via:
    - `gcloud iam service-accounts list --format='value(email)'`
  - The YAML field links to the Service Accounts console page.

How It Works
- Dispatch (trigger)
  - Optionally verifies OIDC bearer from Pub/Sub push (iss/aud/email)
  - Decodes `message.data` to get `historyId`/`emailAddress`
  - Calls `users.history.list(startHistoryId=...)` once to gather deltas
  - Splits changes per family and stores pending batches in Dify storage
  - Returns the list of concrete event names for Dify to execute
- Events
  - Read the pending batch for their family
  - `gmail_message_added` fetches full message metadata (headers, attachments meta)
  - Output matches the event YAML `output_schema`

Event Outputs (high-level)
- `gmail_message_added`
  - `history_id`: string
  - `messages[]`: id, threadId, internalDate, snippet, sizeEstimate, labelIds, headers{From,To,Subject,Date,Message-Id}, has_attachments, attachments[]
- `gmail_message_deleted`
  - `history_id`: string
  - `messages[]`: id, threadId
- `gmail_label_added` / `gmail_label_removed`
  - `history_id`: string
  - `changes[]`: id, threadId, labelIds

Lifecycle & Refresh
- Create: `users.watch` with `topicName`, optional `labelIds`/`labelFilterAction`
- Refresh: `users.watch` again before expiry (Gmail watch is time-limited). If `expiration` not provided, plugin targets ~6 days
- Delete: `users.stop`

Testing
- Send an email to the watched mailbox (INBOX). You should see `gmail_message_added`
- Mark read/unread (UNREAD label removed/added) triggers label events
- Delete an email triggers `gmail_message_deleted`
 - Tip: You can view recent deliveries in Pub/Sub subscription details; Dify logs/console will show trigger and event traces.

Troubleshooting
- Nothing triggers: ensure topic exists, Gmail has publisher role on the topic, and push subscription points to Dify endpoint
- 401/403 at dispatch: OIDC settings mismatch; verify service account and audience
- `historyId` out of date: plugin resets checkpoint to the latest notification and skips the batch
- OAuth issues: re-authorize the provider; token is validated by `users/me/profile`

References
- Gmail Push: https://developers.google.com/workspace/gmail/api/guides/push
- History: https://developers.google.com/gmail/api/reference/rest/v1/users.history/list
- Messages: https://developers.google.com/gmail/api/reference/rest/v1/users.messages/get