New to Kestra?
Use blueprints to kickstart your first workflows.
Send a SendGrid email notification when a workflow fails
Send a SendGrid email when a Kestra workflow fails. Automate failure notifications to alert your team of pipeline issues via email in real time.
Categories
id: sendgrid-notify-on-failure
namespace: company.team
triggers:
- id: on_failure
type: io.kestra.plugin.core.trigger.Flow
dependsOn:
- when: "{{ trigger.namespace startsWith 'company' }}"
states:
- FAILED
- WARNING
tasks:
- id: send_email_notification
type: io.kestra.plugin.twilio.sendgrid.SendGridMailExecution
to:
- hello@kestra.io
from: hello@kestra.io
subject: "Kestra Workflow Failure: {{ trigger.executionId }} has failed on {{
taskrun.startDate }}"
sendgridApiKey: "{{ secret('SENDGRID_API_KEY') }}"
executionId: "{{ trigger.executionId }}"
Catch pipeline failures the moment they happen by sending a SendGrid email alert whenever any Kestra workflow in your namespace fails or finishes with a warning. This system flow centralizes failure notifications so your team is paged through email instead of discovering broken data pipelines hours later. It uses a Flow trigger to listen across every execution under a namespace prefix, then delivers a transactional email through the SendGrid API, turning silent execution failures into immediate, actionable alerts.
How it works
- A
io.kestra.plugin.core.trigger.Flowtrigger namedon_failurelistens to executions across your instance. - A single
dependsOnentry scopes it:states: [FAILED, WARNING]fires only on those two outcomes, and thewhenexpression{{ trigger.namespace startsWith 'company' }}matches thecompanynamespace so every nested child namespace is covered too. - When a matching execution occurs, the
send_email_notificationtask of typeio.kestra.plugin.twilio.sendgrid.SendGridMailExecutionsends an email whose subject embeds{{ trigger.executionId }}and the failure timestamp, and passesexecutionIdso recipients can jump straight to the failed run.
What you get
- Real-time email alerts on every failed or warning execution.
- Coverage of an entire namespace tree from a single declarative flow.
- A direct reference to the failing execution ID for fast triage.
- One place to manage failure notifications instead of per-flow alerting.
Who it's for
- Platform and data engineers running shared Kestra namespaces.
- On-call teams that monitor production pipelines.
- Anyone who needs auditable, email-based incident alerts.
Why orchestrate this with Kestra
SendGrid sends email, but it has no awareness of your pipeline runs. Kestra
closes that gap: the event-driven Flow trigger reacts to execution state in
real time, the dependsOn entry scopes alerts to the right namespaces, and
the whole setup is declarative YAML you can version and review. You also gain retries,
execution lineage, and a single system flow that supersedes scattered
per-pipeline notification code.
Prerequisites
- A running Kestra instance.
- A SendGrid account with a verified sender address.
Secrets
SENDGRID_API_KEY: your SendGrid API key used to authenticate the send.
Quick start
- Add the
SENDGRID_API_KEYsecret to your Kestra instance. - Update
toandfromto your verified SendGrid sender and recipients. - Adjust the
whenexpression's namespace prefix to match your own. - Save the flow, then trigger any failing execution in scope to test it.
How to extend
- Add more recipients or a distribution list in the
toarray. - Append a Slack or PagerDuty task alongside the email for multi-channel alerts.
- Broaden or narrow the
stateslist, for example alert onWARNINGonly. - Enrich the email body with execution logs or links back to the Kestra UI.
Links
- Plugin docs: https://kestra.io/plugins/plugin-twilio
Share this Blueprint
Create a Blueprint
Go to the developer platformMore Infrastructure Blueprints
More Core Blueprints
