Postmark Bounce and Spam Rate Sentinel for Kestra

id: postmark-bounce-spam-rate-sentinel
namespace: company.team
description: |
  Every few hours, read the outbound email overview of one Postmark server
  (read-only: no email is sent and no bounce is reactivated) and classify
  sending reputation as HEALTHY, WARNING, CRITICAL, LOW_VOLUME or
  UNREACHABLE. Log quiet runs and alert Slack when the bounce rate or the
  spam complaint rate climbs toward the level that gets sending paused.

inputs:
  - id: lookback_days
    type: INT
    defaults: 1
    displayName: "Lookback Window (days)"
    description: "Read stats from this many days ago through today. Postmark counts
      days in US Eastern time."
  - id: message_stream
    type: STRING
    defaults: "outbound"
    displayName: "Message Stream"
    description: "Postmark message stream ID to judge, for example outbound
      (transactional) or broadcast."
  - id: warning_bounce_rate
    type: FLOAT
    defaults: 5.0
    displayName: "Warning Bounce Rate (%)"
    description: "At or above this bounce rate, the check is WARNING."
  - id: critical_bounce_rate
    type: FLOAT
    defaults: 10.0
    displayName: "Critical Bounce Rate (%)"
    description: "At or above this bounce rate, the check is CRITICAL."
  - id: warning_spam_rate
    type: FLOAT
    defaults: 0.05
    displayName: "Warning Spam Complaint Rate (%)"
    description: "At or above this spam complaint rate, the check is WARNING."
  - id: critical_spam_rate
    type: FLOAT
    defaults: 0.1
    displayName: "Critical Spam Complaint Rate (%)"
    description: "At or above this spam complaint rate, the check is CRITICAL."
  - id: min_sent
    type: INT
    defaults: 200
    displayName: "Minimum Sent"
    description: "Below this many sent emails in the window, the rates are too noisy
      to judge and the run is LOW_VOLUME."

triggers:
  - id: every_four_hours
    type: io.kestra.plugin.core.trigger.Schedule
    description: Check sending reputation every four hours. Shipped disabled; enable
      it once the Postmark server token secret is set and a manual run has been
      verified.
    cron: "40 */4 * * *"
    disabled: true

tasks:
  - id: get_outbound_stats
    type: io.kestra.plugin.core.http.Request
    description: Read the outbound overview (sent, bounced, SMTP API errors, bounce
      rate, spam complaints and spam complaint rate) for the message stream over
      the lookback window from the Postmark Stats API. This is a GET; no email
      is sent.
    uri: "https://api.postmarkapp.com/stats/outbound?messagestream={{
      inputs.message_stream }}&fromdate={{ now() |
      dateAdd(-inputs.lookback_days, 'DAYS') | date('yyyy-MM-dd',
      timeZone='America/New_York') }}&todate={{ now() | date('yyyy-MM-dd',
      timeZone='America/New_York') }}"
    method: GET
    headers:
      Accept: application/json
      X-Postmark-Server-Token: "{{ secret('POSTMARK_SERVER_TOKEN') }}"
    options:
      allowFailed: true
      timeout:
        connectTimeout: PT10S
        readIdleTimeout: PT30S
    retry:
      type: constant
      interval: PT10S
      maxAttempts: 3
    allowFailure: true

  - id: summarize_reputation
    type: io.kestra.plugin.core.debug.Return
    description: Take the sent, bounced and spam complaint counts and the bounce and
      spam complaint rates from the overview, and classify against the bounce
      and spam limits in one jq query. A missing or non-200 response becomes
      UNREACHABLE.
    format: >-
      {{ (outputs.get_outbound_stats.code is not defined or
      outputs.get_outbound_stats.code != 200) ?
      '{"status":"UNREACHABLE","sent":0,"bounced":0,"bounce_rate":0,"spam_complaints":0,"spam_rate":0,"smtp_api_errors":0,"reason":"none"}'
      : (fromJson(outputs.get_outbound_stats.body) | jq(' (.Sent // 0) as $sent
      | ((((.BounceRate // 0) * 100) | floor) / 100) as $br |
      ((((.SpamComplaintsRate // 0) * 1000) | floor) / 1000) as $sr | ($br >= '
      ~ inputs.critical_bounce_rate ~ ') as $cb | ($sr >= ' ~
      inputs.critical_spam_rate ~ ') as $cs | ($br >= ' ~
      inputs.warning_bounce_rate ~ ') as $wb | ($sr >= ' ~
      inputs.warning_spam_rate ~ ') as $ws | {sent: $sent, bounced: (.Bounced //
      0), bounce_rate: $br, spam_complaints: (.SpamComplaints // 0), spam_rate:
      $sr, smtp_api_errors: (.SMTPApiErrors // 0), reason: ([(if $cb or $wb then
      "bounce rate " + ($br | tostring) + "%" else empty end), (if $cs or $ws
      then "spam complaint rate " + ($sr | tostring) + "%" else empty end)] | if
      length == 0 then "none" else join(" and ") end), status: (if $sent < ' ~
      inputs.min_sent ~ ' then "LOW_VOLUME" elif $cb or $cs then "CRITICAL" elif
      $wb or $ws then "WARNING" else "HEALTHY" end)} ') | first | toJson) }}

  - id: route_by_reputation
    type: io.kestra.plugin.core.flow.Switch
    description: Route to a quiet log when reputation is healthy or volume is too
      low to judge, a Slack message when a rate crosses its warning line, or a
      Slack page when a rate crosses its critical line or Postmark could not be
      read.
    value: "{{ fromJson(outputs.summarize_reputation.value).status }}"
    cases:
      "HEALTHY":
        - id: log_healthy
          type: io.kestra.plugin.core.log.Log
          description: Log a quiet line when the check is healthy; no Slack message is sent.
          message: "Postmark {{ inputs.message_stream }} healthy: {{
            fromJson(outputs.summarize_reputation.value).sent }} sent, bounce
            rate {{ fromJson(outputs.summarize_reputation.value).bounce_rate
            }}%, spam complaint rate {{
            fromJson(outputs.summarize_reputation.value).spam_rate }}% over {{
            inputs.lookback_days }} day(s)."
      "LOW_VOLUME":
        - id: log_low_volume
          type: io.kestra.plugin.core.log.Log
          description: Log a quiet line when too few emails were sent to judge; no Slack
            message is sent.
          message: "Postmark {{ inputs.message_stream }}: only {{
            fromJson(outputs.summarize_reputation.value).sent }} email(s) sent
            over {{ inputs.lookback_days }} day(s), below the minimum of {{
            inputs.min_sent }}; rates not judged this run."
      "WARNING":
        - id: alert_warning_reputation
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Post a Slack message when the bounce or spam complaint rate is at
            or above its warning line.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Postmark {{ inputs.message_stream }} WARNING: {{ fromJson(outputs.summarize_reputation.value).reason }} over {{ inputs.lookback_days }} day(s) ({{ fromJson(outputs.summarize_reputation.value).bounced }} bounced and {{ fromJson(outputs.summarize_reputation.value).spam_complaints }} spam complaint(s) out of {{ fromJson(outputs.summarize_reputation.value).sent }} sent). Check the bounce list and recent sends before it grows. Execution {{ execution.id }}."
            }
      "CRITICAL":
        - id: alert_critical_reputation
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the bounce or spam complaint rate is at or above
            its critical line, the level at which sending reputation is at real
            risk.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Postmark {{ inputs.message_stream }} CRITICAL: {{ fromJson(outputs.summarize_reputation.value).reason }} over {{ inputs.lookback_days }} day(s) ({{ fromJson(outputs.summarize_reputation.value).bounced }} bounced and {{ fromJson(outputs.summarize_reputation.value).spam_complaints }} spam complaint(s) out of {{ fromJson(outputs.summarize_reputation.value).sent }} sent). Stop any bulk or imported-list sends and review the recipients now; sending can be paused at this level. Execution {{ execution.id }}."
            }
      "UNREACHABLE":
        - id: alert_unreachable_api
          type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
          description: Page Slack when the outbound overview could not be read, indicating
            an outage, a wrong message stream or an invalid server token.
          url: "{{ secret('SLACK_WEBHOOK') }}"
          payload: |
            {
              "text": "Postmark reputation sentinel UNREACHABLE for stream {{ inputs.message_stream }}: the Stats API did not return a usable response (HTTP {{ outputs.get_outbound_stats.code ?? 'no response' }}). Check the server token and the message stream ID. Execution {{ execution.id }}."
            }
    defaults:
      - id: log_unclassified
        type: io.kestra.plugin.core.log.Log
        description: Fallback for any classification the cases above do not cover, so an
          unexpected value is visible in the logs.
        message: "Postmark reputation sentinel completed with an unexpected
          classification: {{ outputs.summarize_reputation.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
      reputation history stays queryable even if Slack delivery fails.
    message: "Postmark reputation sentinel audit: stream={{ inputs.message_stream }}
      lookback_days={{ inputs.lookback_days }} http={{
      outputs.get_outbound_stats.code ?? 'n/a' }} summary={{
      outputs.summarize_reputation.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 a healthy reputation.
    url: "{{ secret('SLACK_WEBHOOK') }}"
    payload: |
      {
        "text": "Postmark reputation sentinel flow {{ flow.id }} FAILED (execution {{ execution.id }}). Bounce and spam rates are now unknown; check the task logs and the Postmark activity page."
      }

outputs:
  - id: status
    type: STRING
    value: "{{ fromJson(outputs.summarize_reputation.value).status }}"

Transactional email breaks quietly. Someone imports an old customer list, a signup form starts accepting typos, or a marketing send goes out on the transactional stream, and the bounce rate jumps. A few days later password resets and receipts land in spam or stop being delivered, because the provider protects its shared reputation by reviewing or pausing accounts with high bounce or complaint rates. This blueprint turns a scheduled, read-only call to the Postmark Stats API into a sending reputation gate: io.kestra.plugin.core.http.Request reads the outbound overview, one jq query checks the bounce and spam complaint rates against your limits, and the result routes to a quiet log or a Slack alert.

How it works

get_outbound_stats (io.kestra.plugin.core.http.Request) calls GET /stats/outbound with the server token in X-Postmark-Server-Token, for one messagestream and a fromdate/todate window in US Eastern time (Postmark's stats timezone). It is a read: no email is sent and no bounce is reactivated. Retries cover short network blips, and allowFailed plus allowFailure keep an API error from aborting the flow so it can be reported instead.
summarize_reputation (io.kestra.plugin.core.debug.Return) first guards for a missing or non-200 response (UNREACHABLE). Otherwise one jq query reads Sent, Bounced, SMTPApiErrors, BounceRate, SpamComplaints and SpamComplaintsRate. Fewer than min_sent sent is LOW_VOLUME; a bounce or spam complaint rate at or above its critical line is CRITICAL; at or above its warning line is WARNING; otherwise HEALTHY. The summary names which rate tripped.
route_by_reputation (io.kestra.plugin.core.flow.Switch) branches on that classification: HEALTHY and LOW_VOLUME log quietly, WARNING posts a Slack note, CRITICAL and UNREACHABLE page Slack. A defaults fallback logs anything unexpected.
log_audit_result (io.kestra.plugin.core.log.Log) writes one audit line per run with the HTTP status and the full summary.
The flow-level errors block pages Slack if the flow itself fails, and the every_four_hours trigger runs at 40 minutes past every fourth hour, shipped disabled: true.

What you get

A read-only reputation check every four hours with no custom scripting and no extra plugin to install.
A status output (HEALTHY / WARNING / CRITICAL / LOW_VOLUME / UNREACHABLE) other flows can gate on, for example to hold a bulk send or a list import while rates are high.
Slack messages that say which rate tripped, with the bounced, complaint and sent counts.
An audit line on every run, separate from Slack.

Who it's for

SaaS and e-commerce teams that send receipts, password resets and notifications through Postmark.
Growth teams that also send broadcasts on a separate Postmark stream and want each stream judged on its own.
Teams that already run their notification and alerting workflows in Kestra.

Why orchestrate this with Kestra

Postmark shows bounce and spam rates on its dashboard and can send a webhook per bounce, but nothing tells your team that the rate crossed a line today. Kestra turns a plain, read-only API call into a scheduled, typed classification with retries, a failure path and an execution history, and the status output lets your sending flows pause themselves before the provider does it for you.

Prerequisites

A Postmark server and its Server API token (the server's API Tokens tab).
The ID of the message stream to judge, shown on the stream's settings page (outbound is the default transactional stream).
A Slack incoming webhook for the WARNING, CRITICAL, UNREACHABLE and flow-failure alerts.

Secrets

POSTMARK_SERVER_TOKEN: the Server API token of the Postmark server to watch.
SLACK_WEBHOOK: Slack incoming webhook used for every alert branch and the flow-failure alert.

In Kestra OSS, secrets are supplied as environment variables prefixed SECRET_ and base64-encoded, for example SECRET_POSTMARK_SERVER_TOKEN=$(echo -n 'your-server-token' | base64), and read back with {{ secret('POSTMARK_SERVER_TOKEN') }}. Use the Enterprise secrets backend for encryption at rest and access control.

Quick start

Add POSTMARK_SERVER_TOKEN and SLACK_WEBHOOK as secrets.
Run the flow manually with a low min_sent and compare the counts and rates in the logs with the stream's statistics page in Postmark.
Lower warning_bounce_rate below your current rate to see the WARNING path, then set it back.
Enable every_four_hours.

How to extend

Run one execution per message stream (transactional and broadcast) with its own limits.
Add GET /bounces?type=HardBounce&count=50&offset=0 to list the addresses behind a spike in the same alert.
Pass a tag query parameter to judge one email type, such as receipts or password resets.
Store the last status in a KV store and alert only when it changes.

Inputs

lookback_days: type INT, default 1.
message_stream: type STRING, default outbound.
warning_bounce_rate: type FLOAT, default 5.0 (percent).
critical_bounce_rate: type FLOAT, default 10.0 (percent).
warning_spam_rate: type FLOAT, default 0.05 (percent).
critical_spam_rate: type FLOAT, default 0.1 (percent).
min_sent: type INT, default 200.

Outputs

status: one of HEALTHY, WARNING, CRITICAL, LOW_VOLUME, UNREACHABLE.
Example path: {{ fromJson(outputs.summarize_reputation.value).reason }} for the rate that tripped.

Pitfalls

Postmark's stats are per day in US Eastern time, so lookback_days: 1 covers yesterday and today, not a rolling 24 hours.
The Stats API takes a server token, not an account token; with the wrong token the run reports UNREACHABLE.
The defaults are starting points, not Postmark policy; tune them to your own sending history.
This flow only reads; it never sends an email or reactivates a bounced address.