A filter audience is worked out again every time the broadcast sends. People join and leave it as their records change. Nobody is put in by hand.
There are two kinds. Pick by where the people are:
| The people are… | Use | Saved as | The broadcast lists it as |
|---|---|---|---|
| contacts, picked by fields on the contact (city, tag, group, signup date, status) | a smart customer group | customer_group with groupType dynamic | <group sk> |
| rows in any other collection: form answers, orders, carts, signups, or a join of several | a dynamic list | dataviz_item with type query | query:<item sk> |
A smart group is also a real customer group: it shows on the Customer Groups tab with its count, and other broadcasts can reuse it. A dynamic list exists only for broadcasts.
A broadcast sends real messages to real people. This skill stops at a draft.
Ask first
- Who, in their words. "Customers in Austin who bought in the last 90 days." Turn it into rules (below) and read them back in plain words before saving.
- Which channel? Email reaches people with an address; SMS, WhatsApp and voice reach people with a phone number. The same filter gives different counts.
- For a dynamic list on a repeating broadcast: should each record be sent to once (a cart is emailed once, ever), or should everyone it finds get every run (a weekly newsletter)?
- The message and the sender, as for any draft (email, SMS).
Rules
Both kinds use the same rule engine. A rule is { "field": "<field>", "operator": "<operator>", "value": "<value>" }.
fieldis a field of the record, written withoutdata.(address.city,tags,email).sk,createdate,modifydate,authorandstateare the record's own fields and are written as they are.- Text matches ignore case and spaces at the ends. A list field (
tags,groups) matches when any of its values does. Dates compare as dates.
operator | Means | value |
|---|---|---|
equals / not_equals | is / is not | one value |
in / not_in | is any of / none of | values separated by commas |
contains / not_contains | has the text in it / doesn't | text |
starts_with / ends_with | begins / ends with | text |
gt gte lt lte | > ≥ < ≤ | a number or a date |
before / after | earlier / later than | a date |
in_last_days / not_in_last_days | within the last N days of the send / not | N |
is_empty / is_not_empty | has no value / has one | none |
Rules are joined by all (every rule holds) or any (at least one holds). An unknown operator matches no one.
Steps
1. Try the rules before saving
Preview, so the person sees real names before anything is saved.
- Smart group:
call_appenginePOST /crm/customer-groups/matchwith{ "group": { "groupType": "dynamic", "addRules": [<rules>], "addRulesMatch": "all" } }. The answer is the contacts it holds now (total, a page ofdata) and thequeryit ran. - Dynamic list:
POST /broadcast/audience/query-previewwith{ "collection": "<collection name>", "rules": [<rules>], "rulesMatch": "all", "channel": "email" }. The answer has the first rows,count(rows) andreach(people the channel can reach after unsubscribes are taken out).
If the count is far from what the person expects, show a few names and fix the rules. Don't save a list nobody checked.
Hands on: the rules and how many they reach. Check: read the rules back in words ("contacts whose city is Austin and whose last order is in the last 90 days: 212 people, 198 with an email").
2. Customers & Benefits (or Broadcast): save it
Smart group. Create a customer_group with create_record:
| Field | Value |
|---|---|
name | e.g. "Austin buyers, last 90 days" |
description | the rules in words |
groupType | dynamic |
addRules | the rules |
addRulesMatch | all or any |
Nobody can be added to or taken out of a smart group by hand. POST /crm/customer-groups/members refuses it, because its rules decide.
Dynamic list. Create a dataviz_item with create_record. This is what the composer's Recipients → Dynamic → Save and use this list writes:
| Field | Value |
|---|---|
type | query |
title | e.g. "Newsletter signups" |
name | lowercase letters, digits and -, 3–80 long, unique, e.g. newsletter-signups-k3f9qa |
content.collection | the collection the rows come from |
content.mode | simple |
content.rules / content.rulesMatch | the rules, and all or any |
content.mongoQuery | "" |
Hands on: the group's sk, or the item's sk.
Check: POST /broadcast/audience/count with { "lists": ["<group sk>"] } or { "lists": ["query:<item sk>"] }, and "channel". It matches the preview. Open a smart group at /customers-benefits?view=groups&groupId=<sk>.
3. Broadcast: the draft addressed to it
Create the email_broadcast draft as in Email campaign draft to a customer group or SMS broadcast to a group, with these audience fields:
| Audience | recipientMethod | selectedLists | Also |
|---|---|---|---|
| smart group | lists | ["<group sk>"] | it can sit beside other groups; a person on two lists gets one message |
| dynamic list | dynamic | ["query:<item sk>"] | one dynamic list, on its own (the composer keeps one and drops other lists); resendEachRun (below) |
resendEachRun (dynamic lists only). Off (the default): each row the list finds is sent to once by this broadcast, across all its runs, so a daily run doesn't email the same cart every day. On: everyone it finds gets every run, as a newsletter should.
Never set status to pending or scheduled, never add a schedule, and never call POST /broadcast/<id>/send.
Hands on: the broadcast's sk.
Check: POST /broadcast/audience/total with { "lists": [<the list ids>], "channel": "<channel>" } gives the count from step 2. Open the draft (/broadcast?openId=<sk>). On Recipients, a smart group is ticked under Lists, or Dynamic shows the saved list with its preview.
Advanced: a written query
When rules can't say it (a join, "carts not changed in 3 days with the owner's email"), a dynamic list can hold a Data Viz pipeline instead: content.mode advanced, content.mongoQuery the pipeline as JSON text, content.rules []. Preview it first with POST /broadcast/audience/query-preview and { "collection": "<name>", "pipeline": "<JSON text>", "channel": "email" }.
- It must be a JSON array of stages.
$lookupother collections by their name. - Each row is one person:
email(oremailAddress),phone(orphoneNumber), andnameorfirstName/lastName, at the top of the row or underdata. - Every field of the row can go in the message:
{{data.<field>}}or{{data.<collection>.<field>}}. - It can't use Data Viz's
{{startDate}}/{{endDate}}: a send has no date range. Use"$$NOW"for time rules. A query that fails stops the send with its reason. - Keep
_idorskon rows when "once per record" matters: it is whatresendEachRunoff counts.
A smart group can be written the same way (queryMode advanced, query a filter or pipeline on contacts, as JSON text).
Follow-up to people who didn't open uses one of these on the delivery log.
Stop
Sending is the person's decision. Show the audience in words, the count on the channel, the message and the sender, and say the audience is worked out again at the moment it sends, so the number can change. They press Settings & Send → Send Now, or add a time under Settings & Send → Schedule → Add schedule.
When it's done
Tell the person:
- the audience in words, and whether it is a smart group or a dynamic list;
- how many it reaches now, on the channel;
- the draft's name, and that nothing has been sent.
What it can't do yet
- No count is frozen. A filter audience is read at send time. To send to exactly today's people, save them in a static group.
- A dynamic list has no screen of its own outside the composer (Recipients → Dynamic → Open a saved list).
- The older
recipientSegmentfilter on a broadcast (withrecipientType) only does "equals" and "contains" and isn't shown in the composer. Don't use it; use a smart group or a dynamic list.
Don'ts
- Don't use
all-contactsorall-leadsas a shortcut for "everyone who…". They are everyone. - Don't save rules the person hasn't seen in words with a count.
- Don't hand-add people to a smart group, or switch a static group the person built by hand to
dynamic. Its members would be replaced by whatever the rules match.