Delivery recipients through the API

A preview shows who currently matches the delivery without sending messages. To configure this in Cabinet, use Recipients; for an integration, make the request below.

Check the saved audience

Reading requires can_view_deliveries in the delivery's project. Use a server-side API key or OAuth token. DELIVERY_ID is the Senler.io delivery UUID:

curl --fail-with-body \
  "https://api.senler.io/api/deliveries/$DELIVERY_ID/audience-preview?filter_source=saved" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

filter_source=saved uses the delivery's saved conditions. Audience filters supplied alongside it are not applied.

Check other filters without saving

Pass filter_source=query and the required conditions. For example, to check one segment:

curl --fail-with-body --get \
  "https://api.senler.io/api/deliveries/$DELIVERY_ID/audience-preview" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "filter_source=query" \
  --data-urlencode "segment_id=$SEGMENT_ID"

SEGMENT_ID is a Senler.io segment ID, not a Senler.ru group name. Repeat segment_id for multiple segments. lead_ids, channel_ids, and channel_type are also available.

With filter_source=query and no conditions, the preview covers the project's entire eligible audience, not the saved segment. Mandatory subscription, blocking, and project-member exclusions always apply, as do the recipient deduplication rules.

When filter_source is omitted, the API uses supplied nonempty filters, or saved filters if none are supplied. Specify the source explicitly, especially when the user clears filters.

Read the result

The response contains:

filters: the conditions used for this preview;
saved_filters: the saved conditions used when the delivery starts;
filter_source: the source actually used;
total_unique_recipients: the unique recipient count after all mandatory exclusions;
items: the current recipient page;
next_cursor: the next page cursor or null.

For the next page, pass cursor=next_cursor and keep the same source and conditions. A preview does not freeze the audience: leads may change before launch.

The audience_scope field helps check the reach:

all_project: the project's entire eligible audience;
all_selected_channels: the entire eligible audience of the selected channels or channel type;
filtered: selection by leads or segments.

A channel filter alone does not mean a narrow audience. Before sending to the entire audience, confirm the scope and recipient count, not just the message text.

Save the conditions before starting

A preview does not change the delivery. To use the checked conditions, save them in filters with PATCH /api/deliveries/DELIVERY_ID using can_manage_deliveries, then request another preview with filter_source=saved.

The recipient count and the available sending volume are different measures. GET /api/deliveries/DELIVERY_ID/start-preview checks the launch volume against the daily limit. Further actions are covered in starting a delivery.

When using MCP, first find the method and read its schema, then call it with the same conditions. Do not replace an unknown segment ID with an empty filter.