SendGridMailExecution icon
Flow icon
ExecutionStatus icon
ExecutionNamespace icon

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
CoreInfrastructure
id: sendgrid-notify-on-failure
namespace: company.team

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 }}"

triggers:
  - id: on_failure
    type: io.kestra.plugin.core.trigger.Flow
    conditions:
      - type: io.kestra.plugin.core.condition.ExecutionStatus
        in:
          - FAILED
          - WARNING
      - type: io.kestra.plugin.core.condition.ExecutionNamespace
        namespace: company
        comparison: PREFIX

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.Flow trigger named on_failure listens to executions across your instance.
  • Two conditions scope it: io.kestra.plugin.core.condition.ExecutionStatus fires only on FAILED or WARNING executions, and io.kestra.plugin.core.condition.ExecutionNamespace matches the company namespace with comparison: PREFIX so every nested child namespace is covered too.
  • When a matching execution occurs, the send_email_notification task of type io.kestra.plugin.twilio.sendgrid.SendGridMailExecution sends an email whose subject embeds {{ trigger.executionId }} and the failure timestamp, and passes executionId so 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, conditions scope 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

  1. Add the SENDGRID_API_KEY secret to your Kestra instance.
  2. Update to and from to your verified SendGrid sender and recipients.
  3. Adjust the ExecutionNamespace condition to match your namespace prefix.
  4. 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 to array.
  • Append a Slack or PagerDuty task alongside the email for multi-channel alerts.
  • Broaden or narrow the status conditions, for example alert on WARNING only.
  • Enrich the email body with execution logs or links back to the Kestra UI.

Links

Tasks
SendGridMailExecution icon
Send Grid Mail Execution
Flow icon
Flow
ExecutionStatus icon
Execution Status
ExecutionNamespace icon
Execution Namespace
Share this Blueprint
Create a Blueprint
Go to the developer platform

More Infrastructure Blueprints

Ansible Scalability, Deploy Configuration Files to Multiple Servers at Scale

Provision AWS EC2 servers and deploy configuration files across all of them at scale with Ansible.

AwsCLI icon
AnsibleCLI icon
Cloud Infrastructure
Security & Compliance, Detect and Alert on Infrastructure Configuration Drift with Ansible

Run an Ansible playbook nightly and alert Slack only when configuration drift is corrected on a host.

AnsibleCLI icon
Process icon
ForEach icon
SlackIncomingWebhook icon
Schedule icon
Infrastructure
Rolling Ansible Patch Wave with Health Gates

Roll out Ansible OS patches across your fleet one wave at a time, health-checking between waves and halting on the first failure.

ForEach icon
AnsibleCLI icon
Process icon
Request icon
SlackIncomingWebhook icon
Schedule icon
Infrastructure

More Core Blueprints

Built by our Customer Success Team
Self-Healing Recovery Loop with Retries, Rollback, and an SLA Gate

Four resilience patterns in one flow: automatic retries, rollback on failed smoke tests, a self-healing recovery loop, and an SLA breach that triggers automated RCA.

Request icon
Sequential icon
Set icon
Sleep icon
Fail icon
LoopUntil icon
+3
Core
Run Shell Scripts and Shell commands in a working directory using a Process Task Runner

Run multi-step Bash scripts and shell commands that share files in a single working directory.

WorkingDirectory icon
Script icon
Process icon
Commands icon
Core
Convert Natural Language Prompts to Structured Todoist Tasks with Deepseek AI

Turn plain-English to-do prompts into structured Todoist tasks using DeepSeek AI structured output and a ForEach HTTP loop.

ChatCompletion icon
ForEach icon
Request icon
AI Business Core
See How

New to Kestra?

Use blueprints to kickstart your first workflows.

Get Started