New to Kestra?
Use blueprints to kickstart your first workflows.
Set up alerts for failed workflow executions using Email
Send automatic email alerts on failed or warning Kestra executions with a single system flow, centralizing failure notifications across every namespace.
Categories
id: failure-alert-email
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: username@example.com
password: "{{ secret('EMAIL_PASSWORD') }}"
host: smtp.com
port: 465
subject: Failed Execution - {{ trigger.executionId }}
htmlTextContent: "{{ trigger.executionId }}"
Stop discovering broken pipelines hours after they fail. This system flow sends an email alert the moment any workflow execution in your Kestra instance finishes with a FAILED or WARNING status, giving on-call engineers and data teams a single, centralized place to manage failure notifications instead of wiring per-flow alerting into every pipeline.
How it works
- A
io.kestra.plugin.core.trigger.Flowtrigger listens across the instance for completed executions. - A
dependsOnentry withstates: [FAILED, WARNING]filters those executions, matching only those two statuses. - When a match occurs, the
notifytask (io.kestra.plugin.email.MailSend) sends an SMTP email. ThesubjectandhtmlTextContentare templated with{{ trigger.executionId }}so the alert identifies the failed execution. - Because it lives in the
systemnamespace, the flow reacts to executions in other namespaces without any changes to those flows.
What you get
- Automatic email notifications for every failed or warning execution.
- Centralized alerting logic defined once, not duplicated per flow.
- The failing execution ID included in the message for fast triage.
- Instance-wide coverage out of the box.
Who it's for
- On-call and platform engineers who need immediate failure signals.
- Data and analytics teams running scheduled pipelines.
- Teams standardizing observability and incident response across many flows.
Why orchestrate this with Kestra
Most tools alert only on their own jobs. Kestra's event-driven Flow trigger reacts to the outcome of any execution across the whole instance, so one declarative YAML flow covers your entire platform. You get retries, full execution lineage, and a single source of truth for failure handling that no individual task scheduler or cron job can provide.
Prerequisites
- A Kestra instance with the Email plugin available.
- SMTP server access (host, port, and credentials).
Secrets
EMAIL_PASSWORD: the SMTP account password used by thenotifytask to authenticate.
Quick start
- Add the
EMAIL_PASSWORDsecret to your Kestra instance. - Update the
from,to,username,host, andportvalues in thenotifytask to match your SMTP provider. - Save the flow in the
systemnamespace and enable the trigger. - Trigger a test failure to confirm the alert email arrives.
How to extend
- Restrict alerts to specific namespaces by adding a
whenexpression checkingtrigger.namespaceto thedependsOnentry. - Enrich the email body with execution metadata, logs, or a link back to the Kestra UI.
- Swap or add notification channels (Slack, PagerDuty, webhooks) alongside the email task.
Links
More Core Blueprints
More System Blueprints
