id: brevo-email-deliverability-sentinel
namespace: company.team
description: |
Every few hours, read the aggregated transactional email report from the
Brevo API (read-only: no email is sent and no contact is changed) and
classify deliverability as HEALTHY, WARNING, CRITICAL, LOW_VOLUME or
UNREACHABLE. Log quiet runs and alert Slack when hard bounces, spam
complaints or blocked sends rise, before the sending reputation and
inbox placement of order and OTP emails suffer.
inputs:
- id: lookback_days
type: INT
defaults: 1
displayName: "Lookback Window (days)"
description: "How many days of transactional email to aggregate (Brevo allows 1 to 90)."
- id: warning_bounce_rate
type: FLOAT
defaults: 2.0
displayName: "Warning Hard Bounce Rate (%)"
description: "At or above this share of hard bounces among requests, the check
is WARNING."
- id: critical_bounce_rate
type: FLOAT
defaults: 5.0
displayName: "Critical Hard Bounce Rate (%)"
description: "At or above this share of hard bounces among requests, the check
is CRITICAL."
- id: warning_spam_rate
type: FLOAT
defaults: 0.1
displayName: "Warning Spam Complaint Rate (%)"
description: "At or above this share of spam complaints among delivered emails,
the check is WARNING (mailbox providers ask senders to stay below 0.1%)."
- id: critical_spam_rate
type: FLOAT
defaults: 0.3
displayName: "Critical Spam Complaint Rate (%)"
description: "At or above this share of spam complaints among delivered emails,
the check is CRITICAL."
- id: min_requests
type: INT
defaults: 100
displayName: "Minimum Requests"
description: "Below this many sends in the window, the rates are too noisy to
judge and the run is LOW_VOLUME."
triggers:
- id: deliverability_check
type: io.kestra.plugin.core.trigger.Schedule
description: Check deliverability every 4 hours. Shipped disabled; enable it
once the Brevo API key secret is set and a manual run has been verified.
cron: "25 */4 * * *"
disabled: true
tasks:
- id: get_email_report
type: io.kestra.plugin.core.http.Request
description: Read the aggregated transactional email statistics for the lookback
window from the Brevo SMTP statistics API. This is a GET; no email is
sent.
uri: "https://api.brevo.com/v3/smtp/statistics/aggregatedReport?days={{
inputs.lookback_days }}"
method: GET
headers:
api-key: "{{ secret('BREVO_API_KEY') }}"
accept: application/json
options:
allowFailed: true
timeout:
connectTimeout: PT10S
readIdleTimeout: PT30S
retry:
type: constant
interval: PT10S
maxAttempts: 3
allowFailure: true
- id: summarize_deliverability
type: io.kestra.plugin.core.debug.Return
description: Turn the aggregated counters into a hard bounce rate (of requests),
a spam complaint rate (of delivered) and a blocked rate, and classify in
one jq query. A missing or non-200 response becomes UNREACHABLE instead of
looking healthy.
format: >-
{{ (outputs.get_email_report.code is not defined or
outputs.get_email_report.code != 200) ?
'{"status":"UNREACHABLE","requests":0,"delivered":0,"hard_bounce_rate":0,"spam_rate":0,"blocked_rate":0,"range":"n/a"}'
: (fromJson(outputs.get_email_report.body) | jq(' (.requests // 0) as $req
| (.delivered // 0) as $del | (if $req == 0 then 0 else (((.hardBounces //
0) * 10000 / $req) | floor) / 100 end) as $hb | (if $del == 0 then 0 else
(((.spamReports // 0) * 10000 / $del) | floor) / 100 end) as $sp | (if
$req == 0 then 0 else (((.blocked // 0) * 10000 / $req) | floor) / 100
end) as $bl | {requests: $req, delivered: $del, hard_bounces:
(.hardBounces // 0), spam_reports: (.spamReports // 0), blocked: (.blocked
// 0), hard_bounce_rate: $hb, spam_rate: $sp, blocked_rate: $bl, range:
(.range // "n/a"), status: (if $req < ' ~ inputs.min_requests ~ ' then
"LOW_VOLUME" elif $hb >= ' ~ inputs.critical_bounce_rate ~ ' or $sp >= ' ~
inputs.critical_spam_rate ~ ' then "CRITICAL" elif $hb >= ' ~
inputs.warning_bounce_rate ~ ' or $sp >= ' ~ inputs.warning_spam_rate ~ '
then "WARNING" else "HEALTHY" end)} ') | first | toJson) }}
- id: route_by_deliverability
type: io.kestra.plugin.core.flow.Switch
description: Route to a quiet log when deliverability is healthy or volume is
too low to judge, a Slack message when bounces or complaints cross the
warning line, or a Slack page when they cross the critical line or Brevo
could not be read.
value: "{{ fromJson(outputs.summarize_deliverability.value).status }}"
cases:
"HEALTHY":
- id: log_healthy
type: io.kestra.plugin.core.log.Log
message: "Brevo deliverability healthy for {{
fromJson(outputs.summarize_deliverability.value).range }}: {{
fromJson(outputs.summarize_deliverability.value).requests }} sent,
hard bounces {{
fromJson(outputs.summarize_deliverability.value).hard_bounce_rate
}}%, spam complaints {{
fromJson(outputs.summarize_deliverability.value).spam_rate }}%."
"LOW_VOLUME":
- id: log_low_volume
type: io.kestra.plugin.core.log.Log
message: "Brevo deliverability: only {{
fromJson(outputs.summarize_deliverability.value).requests }}
email(s) in {{
fromJson(outputs.summarize_deliverability.value).range }}, below the
minimum of {{ inputs.min_requests }}; rates not judged this run."
"WARNING":
- id: alert_warning_deliverability
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Post a Slack message when the hard bounce or spam complaint rate is
at or above the warning line.
url: "{{ secret('SLACK_WEBHOOK') }}"
payload: |
{
"text": "Brevo deliverability WARNING for {{ fromJson(outputs.summarize_deliverability.value).range }}: hard bounces {{ fromJson(outputs.summarize_deliverability.value).hard_bounce_rate }}% ({{ fromJson(outputs.summarize_deliverability.value).hard_bounces }}), spam complaints {{ fromJson(outputs.summarize_deliverability.value).spam_rate }}% ({{ fromJson(outputs.summarize_deliverability.value).spam_reports }}), blocked {{ fromJson(outputs.summarize_deliverability.value).blocked_rate }}% of {{ fromJson(outputs.summarize_deliverability.value).requests }} sent. Clean the list or check the latest template before mailbox providers throttle you. Execution {{ execution.id }}."
}
"CRITICAL":
- id: alert_critical_deliverability
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Page Slack when the hard bounce or spam complaint rate is at or
above the critical line, which puts the sending domain's reputation
and inbox placement at risk.
url: "{{ secret('SLACK_WEBHOOK') }}"
payload: |
{
"text": "Brevo deliverability CRITICAL for {{ fromJson(outputs.summarize_deliverability.value).range }}: hard bounces {{ fromJson(outputs.summarize_deliverability.value).hard_bounce_rate }}%, spam complaints {{ fromJson(outputs.summarize_deliverability.value).spam_rate }}%, blocked {{ fromJson(outputs.summarize_deliverability.value).blocked_rate }}% of {{ fromJson(outputs.summarize_deliverability.value).requests }} sent. Order, OTP and password emails may start landing in spam. Pause bulk sends and investigate now. Execution {{ execution.id }}."
}
"UNREACHABLE":
- id: alert_unreachable_api
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Page Slack when the statistics API could not be read, indicating an
outage or an invalid API key.
url: "{{ secret('SLACK_WEBHOOK') }}"
payload: |
{
"text": "Brevo deliverability sentinel UNREACHABLE: the SMTP statistics API did not return a usable response (HTTP {{ outputs.get_email_report.code ?? 'no response' }}). Check the API key. Execution {{ execution.id }}."
}
defaults:
- id: log_unclassified
type: io.kestra.plugin.core.log.Log
message: "Brevo deliverability sentinel completed with an unexpected
classification: {{ outputs.summarize_deliverability.value }}."
- id: log_audit_result
type: io.kestra.plugin.core.log.Log
description: Record one audit line for every run, whichever branch fired, so the
deliverability history stays queryable even if Slack delivery fails.
message: "Brevo deliverability sentinel audit: lookback_days={{
inputs.lookback_days }} http={{ outputs.get_email_report.code ?? 'n/a' }}
summary={{ outputs.summarize_deliverability.value }} execution={{
execution.id }}."
errors:
- id: alert_flow_failure
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Alert Slack when the sentinel flow itself fails, so a broken check
is never mistaken for healthy deliverability.
url: "{{ secret('SLACK_WEBHOOK') }}"
payload: |
{
"text": "Brevo deliverability sentinel flow {{ flow.id }} FAILED (execution {{ execution.id }}). Email deliverability is now unknown; check the task logs and the Brevo statistics page."
}
outputs:
- id: status
type: STRING
value: "{{ fromJson(outputs.summarize_deliverability.value).status }}"