Audience Filtering

Narrow a scheduled campaign send to a real-time list of leads from your side

For the endpoint spec (URL, auth, request/response shapes, examples), see Filter Send Audience.

This page covers when to use audience filtering, how to configure it on a send, and the rules that apply when the filter event lands.

Why

Most sends go to your full uploaded audience. Sometimes you want to narrow a specific send based on signals that aren’t known at upload time — e.g. “for tomorrow’s send, only message leads who completed step X by tonight.”

Audience filtering lets your system POST a list of leads to include or exclude for a specific send, up until 5 minutes before that send fires.

Enabling on a send

When adding a send to your campaign sequence, toggle “Apply filter from inbound webhook” on. The send will then accept filter events at the audience-filter endpoint until its filter deadline (5 min before its scheduled time).

A send with the filter off ignores any incoming filter events targeting it.

Authentication setup

Pick the auth mode for inbound endpoints once per organization, in Settings → Webhooks:

• API key (default) — bearer-token auth using any active org-level API key.
• HMAC — generate a signing key, sign the raw request body with HMAC-SHA256, send as X-Setter-Signature: sha256=<hex>. Multiple signing keys can be active concurrently for rotation.

The same auth setting applies to all inbound endpoints for your org (audience filtering, lead events, etc.).

When the filter is applied

The send’s recipient list is materialized about 60 seconds before scheduledFor. At that moment, the materializer:

1. Loads every lead in the campaign’s audience whose ingest status is ok
2. Drops opted-out phone numbers
3. If the send has the audience filter enabled, applies the most recent filter event for that send: include keeps only listed leads; exclude removes them
4. Inserts one row per remaining lead into the per-recipient send queue

So if you POST multiple filter events before the deadline, only the latest one matters.

Lead matching

A lead in your filter payload matches an audience lead if either of these is true:

• The payload’s externalId matches the audience lead’s external_id column from the CSV (case-sensitive).
• The payload’s phoneE164 matches the normalized E.164 stored on the audience lead.

Leads in your filter payload that don’t match any audience lead are silently ignored (logged).

Combining with the event filter

A send can have both an audience filter (this page) and an event filter (matching against Send Lead Event) configured. Both must keep a recipient for them to receive the message — the filters are ANDed.