Skip to main content
An audience is a group Courier maintains. You write rules, and membership updates as profiles change. Target one on a send with audience_id:
Create or update an audience with , passing a filter. See the for the full schema.

​
How it works

Each condition in a filter names a profile path, an operator, and a value.

​
Audience operators

Console labels and their API values:

​
Combining conditions

A filter is a group with an operator and a filters array. Use AND so every condition must match, or OR so at least one must. A condition inside filters can be another group. That nests rules like “on the pro plan AND (admin OR owner)“:

​
How membership works

Courier pre-computes membership instead of evaluating every rule against every profile at send time. When a profile changes, Courier updates whether that user belongs to each audience. Changing an audience’s rules starts a rebuild of its membership list. At send time, Courier reads the stored membership. A rebuild of a large audience can take many minutes. A send during the rebuild reads a partially updated list. Wait for membership to settle before a large send. Check and spot-check .

​
Scoping a send to a tenant

context.tenant_id on a send controls branding, preferences, and template variables for that tenant. It does not restrict which audience members receive the message. To send only to users in one tenant, add an inline filters array on the recipient. Use the MEMBER_OF operator with path: tenant_id:
A user must have tenant membership to pass the filter. Set it with .

​
Limits & behavior

  • MEMBER_OF is a send-time filter, not an audience rule. It is not one of the audience comparison operators. Use it inline on the recipient to scope a send by tenant.
  • Membership is materialized, so it can lag a rule change. A large audience rebuilds over minutes, and sends read the stored list. Wait for it to settle before a critical blast.
  • Audiences are eventual, lists are exact. An audience member appears once the profile change propagates. A member is present the moment you add them.

​
FAQ

Membership is pre-computed and rebuilds after a rule change. For a large audience that takes many minutes. Sends during the rebuild read a partially updated list. Wait for membership to settle before sending.
Use an audience when membership follows from profile data and should update itself, like all pro-plan users. Use a when you decide membership by hand.
Any condition in a filters array can be a group with its own operator and filters.