Creator Center
/Trigger/Gmail Trigger
app icon

Gmail Trigger

Verified by Dify
No ratings yet
4
L
langgenius/gmail_trigger

Gmail push notifications trigger provider for Dify.

Utilities

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:
    • (new messages)
    • (deleted messages)
    • (labels added to messages)
    • (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 API enabled (configured at tenant-level by administrator)

Step-by-step Setup

  1. Install the plugin in Dify
  • Options:
    • If packaged as , import it in Dify’s Plugin Center (Plugins → Import).
    • For local development runs, provision the environment from / first (for example, ) so the runtime uses the locked dependencies.
  1. Configure GCP resources (Administrator, one-time setup)

  • Create or select the Google Cloud project that will host your Pub/Sub resources. Make sure the following APIs are enabled (APIs & Services → Library):

    • 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 a dedicated service account and grant Pub/Sub permissions:

    1. Go to IAM & Admin → Service Accounts → Create Service Account.
      Console URL: https://console.cloud.google.com/iam-admin/serviceaccounts

      Screenshot:

    2. Assign the role to this service account or select "Pub/Sub Admin" role which already includes the necessary permissions (required so the plugin can create topics, subscriptions, and update IAM policies automatically).

      • Alternatively, a custom role must include: , , , , , , .

        Screenshot:

    3. Create a JSON key for this service account and download it securely.
      Screenshot:

  • Note your Google Cloud Project ID (displayed on the project dashboard or IAM page).

  1. Configure OAuth client for the plugin (Administrator, one-time setup)

  • In Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth client ID.
    Console URL: https://console.cloud.google.com/apis/credentials

    Screenshot:

    • Application type: Web application
    • Authorized redirect URIs: copy the redirect URI shown in Dify when you set up the plugin (e.g., )

  • Capture the generated Client ID and Client Secret for later use.

  1. Enter OAuth client parameters in Dify
  • In the plugin configuration form:
    • : The OAuth client ID created above.
    • : The corresponding client secret.
    • : The Google Cloud project ID with Pub/Sub enabled.
    • : Paste the full JSON key created for the service account (keep it private).
  • Dify will automatically derive a per-user Pub/Sub topic when the end user authorizes the plugin.
  1. User: Authorize and create subscription
  • Click "Authorize" to complete OAuth (gmail.readonly scope)
  • Create a Gmail subscription with optional parameters:
    • (optional): Scope to specific labels (INBOX, UNREAD, etc.)
      • Docs: https://developers.google.com/gmail/api/reference/rest/v1/users.labels/list
    • Properties (optional, for enhanced security):
      • : Enforce OIDC bearer verification
      • : Webhook endpoint URL (auto-filled)
      • : Service account used for Push subscription

What happens automatically:

  • Plugin creates/reuses a Pub/Sub Topic in your GCP project
  • Plugin grants Gmail API publisher permission to the topic
  • Plugin creates a dedicated Push subscription for this user
  • Plugin calls Gmail API to start monitoring
  • On unsubscribe, plugin cleans up the Push subscription (topic is preserved for reuse)

Where To Get OIDC Values

    • Use the exact webhook endpoint URL shown in the Dify subscription details (Endpoint). Example:
    • The YAML field includes a URL to Google docs for the claim: see the OIDC token reference.
    • The service account used by the Pub/Sub push subscription (set via ).
    • Find it under Google Cloud Console → IAM & Admin → Service Accounts, or via:
    • 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 to get /
    • Calls 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
    • fetches full message metadata (headers, attachments meta)
    • Output matches the event YAML

Event Outputs (high-level)

    • : string
    • : id, threadId, internalDate, snippet, sizeEstimate, labelIds, headers{From,To,Subject,Date,Message-Id}, has_attachments, attachments[]
    • : string
    • : id, threadId
  • /
    • : string
    • : id, threadId, labelIds

Attachment Handling

  • The trigger attempts to upload at most 20 real attachments (with or inline content), skipping individual files larger than 5 MiB.
  • is the only externally exposed download address; identifies its origin ( for original links or for Dify mirror).
  • When attachments are successfully uploaded to Dify, both and (Gmail/Drive original address) are returned; if not mirrored, is omitted.
  • Gmail often returns Drive links for oversized attachments, or provides sharing addresses directly in the message body. The event scans text/HTML content to extract these links and returns them as attachment items for unified handling by callers.
  • Callers only need to use , determining whether to access Gmail/Drive directly or go through Dify storage based on .

Lifecycle & Refresh

  • Create: Plugin auto-provisions Pub/Sub, then calls with and optional
  • Refresh: is called again before expiry (Gmail watch is time-limited, ~7 days)
  • Delete: Calls and cleans up the Push subscription

Testing

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

Troubleshooting

  • Plugin fails to create subscription: Check GCP credentials are correctly configured in OAuth client parameters
  • Nothing triggers: Verify Gmail API and Pub/Sub API are enabled in your GCP project
  • 401/403 at dispatch: OIDC settings mismatch; verify service account and audience
  • out of date: Plugin resets checkpoint to the latest notification and skips the batch
  • OAuth issues: Re-authorize; ensure gmail.readonly scope is granted

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
CATEGORY
Trigger
VERSION
0.1.2
langgenius·Updated 16 days ago
REQUIREMENTS
Maximum memory
1MB
Maximum storage
1MB
Access domain

Some outbound calls build their address at runtime, so the list may be incomplete.

Detected
Detected
Detected
Security
Security Rating

Last checked 10/07/2026 11:56 AM · version 0.1.2

Give a rate
SHARE WITH