Klaviyo Pre-Send Audience Size Guardrail in Kestra

id: klaviyo-recipient-estimation-alert
namespace: company.marketing

labels:
  team: marketing
  guardrail: klaviyo-presend

inputs:
  - id: campaign_id
    type: STRING
    description: Klaviyo campaign ID to estimate the audience for before sending.
    defaults: "01HXXXXXXXXXXXXXXXXXXXXXXX"
  - id: min_recipients
    type: INT
    description: |
      Minimum acceptable estimated audience size; below this is flagged. This
      default (500) is illustrative. Set it per list or segment to match your
      own guardrails.
    defaults: 500
  - id: max_recipients
    type: INT
    description: |
      Maximum acceptable estimated audience size; above this is flagged. This
      default (250000) is illustrative. Set it per list or segment, or derive
      it from a percentage of total list size.
    defaults: 250000
  - id: fail_on_out_of_range
    type: BOOLEAN
    description: |
      When true, an out-of-range estimate fails the execution after alerting,
      so a parent send-preparation flow calling this as a subflow can gate on
      the FAILED state. When false, the flow only alerts and stays SUCCESS.
    defaults: true

pluginDefaults:
  - type: io.kestra.plugin.klaviyo
    values:
      apiKey: "{{ secret('KLAVIYO_API_KEY') }}"
  - type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    values:
      url: "{{ secret('SLACK_WEBHOOK_URL') }}"

tasks:
  - id: estimate_recipients
    type: io.kestra.plugin.klaviyo.campaign.GetRecipientCount
    description: |
      Read the current recipient estimate for the campaign. Klaviyo computes
      estimates asynchronously, so a freshly created campaign may not have a
      ready value yet; the downstream check distinguishes "estimate
      unavailable" from a real zero so the guardrail does not false-alarm.
    campaignIds:
      - "{{ inputs.campaign_id }}"
    fetchType: FETCH_ONE
    retry:
      type: constant
      interval: PT30S
      maxAttempt: 4
    timeout: PT5M

  - id: route_estimate
    type: io.kestra.plugin.core.flow.If
    description: Branch on whether the estimate is available, in range, or out of range.
    condition: "{{
      outputs.estimate_recipients.row.attributes.estimated_recipient_count is
      not null }}"
    then:
      - id: check_audience_size
        type: io.kestra.plugin.core.flow.If
        description: Flag the estimate when it falls outside the acceptable range.
        condition: "{{
          outputs.estimate_recipients.row.attributes.estimated_recipient_count <
          inputs.min_recipients or
          outputs.estimate_recipients.row.attributes.estimated_recipient_count >
          inputs.max_recipients }}"
        then:
          - id: alert_out_of_range
            type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
            description: Warn the marketing channel that the estimate is out of bounds.
            payload: |
              {
                "blocks": [
                  {
                    "type": "header",
                    "text": {
                      "type": "plain_text",
                      "text": "Klaviyo pre-send audience check failed"
                    }
                  },
                  {
                    "type": "section",
                    "fields": [
                      {
                        "type": "mrkdwn",
                        "text": "*Campaign:*\n{{ inputs.campaign_id }}"
                      },
                      {
                        "type": "mrkdwn",
                        "text": "*Estimated recipients:*\n{{ outputs.estimate_recipients.row.attributes.estimated_recipient_count }}"
                      },
                      {
                        "type": "mrkdwn",
                        "text": "*Allowed range:*\n{{ inputs.min_recipients }} to {{ inputs.max_recipients }}"
                      },
                      {
                        "type": "mrkdwn",
                        "text": "*Execution:*\n{{ execution.id }}"
                      }
                    ]
                  },
                  {
                    "type": "context",
                    "elements": [
                      {
                        "type": "mrkdwn",
                        "text": "Review the segment or list filters before scheduling this send."
                      }
                    ]
                  }
                ]
              }
          - id: fail_send_gate
            type: io.kestra.plugin.core.execution.Fail
            description: |
              Fail the execution after alerting so a calling send-prep flow can
              gate on the FAILED state. Skipped when fail_on_out_of_range is
              false.
            condition: "{{ inputs.fail_on_out_of_range }}"
            errorMessage: "Estimated recipients {{
              outputs.estimate_recipients.row.attributes.estimated_recipient_co\
              unt }} out of allowed range {{ inputs.min_recipients }} to {{
              inputs.max_recipients }} for campaign {{ inputs.campaign_id }}."
        else:
          - id: log_in_range
            type: io.kestra.plugin.core.log.Log
            description: Record that the estimate is within range and no alert is needed.
            message: "Estimated recipients {{
              outputs.estimate_recipients.row.attributes.estimated_recipient_co\
              unt }} are within the allowed range for campaign {{
              inputs.campaign_id }}."
    else:
      - id: alert_estimate_unavailable
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: |
          Warn that no estimate is available yet (the estimation job has not
          finished). This is distinct from an estimate of zero and should not
          be treated as a passing check.
        messageText: ":warning: Klaviyo recipient estimate is not available yet for
          campaign {{ inputs.campaign_id }} (execution {{ execution.id }}).
          Re-run once the estimation job completes before sending."

outputs:
  - id: estimated_recipient_count
    type: INT
    description: The estimated recipient count, or null when the estimate is not yet
      available.
    value: "{{ outputs.estimate_recipients.row.attributes.estimated_recipient_count
      ?? null }}"
  - id: in_range
    type: BOOLEAN
    description: |
      True when an estimate was available and within the allowed range. A
      parent flow can read this output instead of (or in addition to) gating on
      the FAILED state.
    value: "{{ (outputs.estimate_recipients.row.attributes.estimated_recipient_count
      is not null) and
      (outputs.estimate_recipients.row.attributes.estimated_recipient_count >=
      inputs.min_recipients) and
      (outputs.estimate_recipients.row.attributes.estimated_recipient_count <=
      inputs.max_recipients) }}"

errors:
  - id: alert_on_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: |
      Alert if the estimation flow itself fails (bad API key, Klaviyo 5xx).
      Note this also fires when fail_on_out_of_range deliberately fails the run
      on an out-of-range audience, which is the intended gate signal.
    messageText: ":rotating_light: {{ flow.namespace }}.{{ flow.id }} failed or
      gated for campaign {{ inputs.campaign_id }} (execution {{ execution.id
      }})."

Catch broken segments and wrong-list mistakes before a Klaviyo campaign goes out. This blueprint is a pre-send audience guardrail: it reads Klaviyo's estimated recipient count for a campaign, compares it against an acceptable range, and raises a Slack alert when the estimate is too small (an over-restrictive filter or empty segment) or too large (the wrong list selected). When configured to gate, it fails the execution after alerting so a parent send-preparation flow can block or pause the send. It is built to run on demand right before scheduling a send, or as a reusable subflow inside a larger marketing-send pipeline.

How it works

estimate_recipients (io.kestra.plugin.klaviyo.campaign.GetRecipientCount) reads the current recipient estimate for the campaign_id input with fetchType: FETCH_ONE, passing the campaign id as the single element of the task's array property.
route_estimate (io.kestra.plugin.core.flow.If) branches on whether an estimate exists. Klaviyo computes estimates asynchronously, so when the value is null the flow takes the else path and posts a distinct "estimate unavailable" warning via io.kestra.plugin.slack.notifications.SlackIncomingWebhook rather than treating a missing value as zero and false-alarming as "too small".
When an estimate is available, the nested check_audience_size If compares it against min_recipients and max_recipients. Out of range posts a rich Slack block message (alert_out_of_range) and, when fail_on_out_of_range is true, runs fail_send_gate (io.kestra.plugin.core.execution.Fail). In range, log_in_range records that no action is needed.

What you get

A pre-send sanity check that flags audience anomalies before delivery.
Clear separation of "estimate not ready yet" from a real zero count.
Slack alerts with campaign id, estimate, allowed range, and execution id.
Two gating signals: a FAILED execution state and an in_range output.
Built-in retries and a flow-level failure alert.

Who it's for

Lifecycle and email marketers who schedule Klaviyo campaigns.
Marketing-ops engineers building automated send-preparation pipelines.
Teams that want a guardrail against sending to the wrong audience.

Why orchestrate this with Kestra

Klaviyo's own scheduler can queue a send, but it has no native step that inspects the estimated audience, blocks on a threshold, and alerts a human before delivery. Kestra fills that gap. You express the whole guardrail as declarative YAML, add a constant retry on estimate_recipients (4 attempts, 30s apart) and a PT5M timeout so a transient 429 or 5xx self-heals, and wire a flow-level errors block that posts a Slack alert with the execution id, so an estimation failure (or a deliberate gate failure) is never silent. Run lineage and outputs are captured per execution, and because this flow emits both a FAILED state and an in_range output, a parent send-prep flow can gate on either, something Klaviyo's scheduler cannot coordinate alone.

Prerequisites

A Klaviyo account with a Private API Key that can read campaign recipient estimation.
A Slack incoming webhook pointing at the channel that owns send approvals.

Secrets

KLAVIYO_API_KEY: Klaviyo Private API Key, used by the estimation task.
SLACK_WEBHOOK_URL: Slack incoming webhook URL used for all alerts.

Quick start

Add the KLAVIYO_API_KEY and SLACK_WEBHOOK_URL secrets to your Kestra namespace.
Run the flow with the campaign_id you are about to send, adjusting min_recipients and max_recipients to match your guardrails (the 500 / 250000 defaults are illustrative).
Leave fail_on_out_of_range true when calling this as a subflow gate; set it false for a notify-only check.

How to extend

Call this flow as a subflow from a send-preparation pipeline and branch on the in_range output or the FAILED state to pause the send.
Derive max_recipients dynamically from a percentage of total list size.
Swap the Slack alert for email or PagerDuty, or add an approval task to require a human sign-off before the send proceeds.
Loop over multiple campaign ids to check a whole send batch at once.

Klaviyo Pre-Send Recipient Estimation Alert

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

Klaviyo Pre-Send Recipient Estimation Alert

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Business Blueprints

Sync Postgres records to Algolia index

AI Slack Chatbot with Per-User Conversation Memory Using OpenAI and KV Store

Generate AI Blog Posts in Your Brand Voice and Publish to WordPress as Draft

Convert Natural Language Prompts to Structured Todoist Tasks with Deepseek AI

Automate Incident Response, Create Jira Tickets, Alert Slack, and Log to Database

AI-Powered Stock Watchlist Analysis with Daily Alerts and PostgreSQL Logging

New to Kestra?