Google Workspace MailReceivedTrigger

Google Workspace MailReceivedTrigger

Certified

Poll Gmail for newly received emails

Polls Gmail for messages newer than the previous interval (default PT5M, min PT1M) and triggers an execution with the matches. Supports search query and label filters, optionally includes spam/trash. Limits processing to maxMessagesPerPoll (default 50).

yaml
type: io.kestra.plugin.googleworkspace.mail.MailReceivedTrigger

Monitor inbox for any new email

yaml
id: gmail_new_messages
namespace: company.team

tasks:
  - id: process_email
    type: io.kestra.plugin.core.log.Log
    message: "New email from {{ trigger.from }}: {{ trigger.subject }}"

triggers:
  - id: watch_inbox
    type: io.kestra.plugin.googleworkspace.mail.MailReceivedTrigger
    clientId: "{{ secret('GMAIL_CLIENT_ID') }}"
    clientSecret: "{{ secret('GMAIL_CLIENT_SECRET') }}"
    refreshToken: "{{ secret('GMAIL_REFRESH_TOKEN') }}"
    interval: PT5M

Monitor specific labels with query filter

yaml
id: gmail_urgent_messages
namespace: company.team

tasks:
  - id: notify_urgent
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {
        "text": "Urgent email: {{ trigger.subject }} from {{ trigger.from }}"
      }

triggers:
  - id: watch_urgent
    type: io.kestra.plugin.googleworkspace.mail.MailReceivedTrigger
    clientId: "{{ secret('GMAIL_CLIENT_ID') }}"
    clientSecret: "{{ secret('GMAIL_CLIENT_SECRET') }}"
    refreshToken: "{{ secret('GMAIL_REFRESH_TOKEN') }}"
    query: "is:unread label:urgent"
    labelIds:
      - INBOX
      - URGENT
    interval: PT2M
Properties

OAuth 2.0 Client ID

The OAuth 2.0 client ID from Google Cloud Console

OAuth 2.0 Client Secret

The OAuth 2.0 client secret from Google Cloud Console

OAuth 2.0 Refresh Token

The OAuth 2.0 refresh token obtained through the authorization flow

OAuth 2.0 Access Token

The OAuth 2.0 access token (optional, will be generated from refresh token if not provided)

Defaultfalse

Specifies whether a trigger is allowed to start a new execution even if a previous run is still in progress.

Defaultfalse

Include spam and trash

Whether to include SPAM and TRASH messages

Initial lookback window

How far back to look on first run; defaults to polling interval

DefaultPT5M
Formatduration

Polling interval

How often to check for new emails; minimum PT1M, default PT5M

SubTypestring

Label filters

Label IDs to restrict search (INBOX, SENT, UNREAD, etc.); empty searches all

Default50

Messages processed per poll

Upper bound on messages processed each poll; default 50

Gmail search query

Gmail search string (e.g., is: unread, from: sender@example.com, subject: important); empty monitors all

Default120

The read timeout for the request (in seconds)

SubTypestring
Default["https://www.googleapis.com/auth/gmail.modify","https://www.googleapis.com/auth/gmail.readonly","https://www.googleapis.com/auth/gmail.send"]

The OAuth scopes to use

List of OAuth 2.0 scopes required for the operation

SubTypestring
Possible Values
CREATEDSUBMITTEDRUNNINGPAUSEDRESTARTEDKILLINGSUCCESSWARNINGFAILEDKILLEDCANCELLEDQUEUEDRETRYINGRETRIEDSKIPPEDBREAKPOINTRESUBMITTED

List of execution states after which a trigger should be stopped (a.k.a. disabled).

Defaulttrue

A condition that determines whether the trigger should run.

A Pebble expression evaluated at trigger time. The trigger fires only when the expression evaluates to a truthy value (true, a non-empty string, a non-zero number). Use this to gate trigger execution on dynamic runtime values such as execution labels, flow variables, or environment conditions.

New messages detected

Messages created since last interval; trigger.subject/from/etc. mirror the first when only one exists

Definitions
bccarray
SubTypestring

The BCC recipient email addresses

ccarray
SubTypestring

The CC recipient email addresses

fromstring

The sender email address

headersobject

The parsed headers of the message

historyIdstring

The ID of the last history record that modified this message

idstring

The immutable ID of the message

internalDatestring
Formatdate-time

The internal message creation timestamp

labelIdsarray
SubTypestring

List of IDs of labels applied to this message

sizeEstimateinteger

Estimated size in bytes of the message

snippetstring

A short part of the message text

subjectstring

The message subject

threadIdstring

The ID of the thread the message belongs to

toarray
SubTypestring

The recipient email addresses

More Plugins in this Category

Prefect
Prefect

Tasks that trigger Prefect deployments and monitor flow runs.

Data

1 tasks

1 blueprints

Azure (EE)
Azure
Enterprise

Tasks that integrate Microsoft Azure services into Kestra enterprise workflows.

CloudDataInfrastructure

7 tasks