New to Kestra?
Use blueprints to kickstart your first workflows.
Set up alerts for failed workflow executions using Gmail
Send automatic Gmail email alerts whenever a Kestra workflow execution fails or warns, with a single reusable flow that centralizes failure notifications.
Categories
id: failure-alert-gmail
namespace: system
triggers:
- id: on_failure
type: io.kestra.plugin.core.trigger.Flow
dependsOn:
- states:
- FAILED
- WARNING
tasks:
- id: notify
type: io.kestra.plugin.email.MailSend
from: alerts@example.com
to: team@company.com
username: "{{ secret('G_EMAIL') }}"
password: "{{ secret('G_APP_PASSWORD') }}"
host: smtp.gmail.com
port: 465
subject: Failed Execution - {{ trigger.executionId }}
htmlTextContent: "{{ trigger.executionId }}"
Catch failed pipelines the moment they break. This system flow sends a Gmail email alert whenever any workflow execution in your Kestra instance ends in a FAILED or WARNING state, so your team learns about broken runs from their inbox instead of from a downstream consumer. Instead of wiring error handling into every flow, you define one centralized failure-alerting pattern that watches all executions and routes notifications through Gmail SMTP. This removes the silent-failure gap that leaves bad data, stalled jobs, and missed SLAs undiscovered until it is too late.
How it works
- A flow trigger (
io.kestra.plugin.core.trigger.Flow) listens to executions across the instance. - A
dependsOnentry withstates: [FAILED, WARNING]filters those events to only executions ending in those states, so healthy runs stay quiet. - When the states match, the
notifytask (io.kestra.plugin.email.MailSend) connects tosmtp.gmail.comon port465and sends an email. - The email
subjectandhtmlTextContentinterpolate{{ trigger.executionId }}, so each alert identifies the exact execution that failed.
What you get
- Centralized, instance-wide failure alerting from a single flow.
- Email delivered through Gmail SMTP to your team distribution address.
- Alerts scoped to real problems (
FAILEDandWARNING) only. - The failing execution id in every message for fast triage.
Who it's for
- Data and platform engineers who own pipeline reliability.
- On-call teams that need push notifications for broken runs.
- Small teams standardizing on Gmail or Google Workspace for alerts.
Why orchestrate this with Kestra
Gmail has no awareness of your pipelines and cannot tell you when a job fails. Kestra closes that gap. The event-driven Flow trigger reacts the instant an execution changes status, condition filtering keeps noise low, retries and full execution lineage are captured automatically, and the entire alerting policy lives in one declarative YAML file you can version and reuse rather than copy-pasting error handlers into every workflow.
Prerequisites
- A Kestra instance with one or more flows to monitor.
- A Gmail or Google Workspace account able to send mail.
- If 2FA is enabled, a Google App password (see how to create one).
Secrets
G_EMAIL: the Gmail address used to authenticate against the SMTP server.G_APP_PASSWORD: the Gmail App password used as the SMTP password.
Quick start
- Add the
G_EMAILandG_APP_PASSWORDsecrets to your Kestra instance. - Update
from,to,host, andportin thenotifytask to match your sender and recipients. - Save the flow and let a monitored workflow fail to confirm the alert lands.
How to extend
- Restrict alerts to specific namespaces by adding a
whenexpression (for example{{ trigger.namespace startsWith 'company' }}) to thedependsOnentry (see the monitoring guide). - Enrich
htmlTextContentwith the flow id, namespace, start date, and a direct link to the execution. - Fan out to multiple recipients or escalation addresses, or add a second notification task for Slack or PagerDuty.
Links
More Core Blueprints
More System Blueprints
