Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Courier provides two approaches for targeting groups of users: static lists for manual curation and dynamic audiences for automated segmentation. Understanding when to use each method helps you build effective targeting strategies for your notifications.

​
Key Features

Courier’s group targeting provides flexible options for reaching the right users:
  • Static Lists - Manually curated collections with complete membership control
  • Dynamic Audiences - Automated segmentation based on profile rules; membership is maintained as profiles change
  • Advanced Operators - Comprehensive filtering with equality, string, numeric, and date comparisons
  • Logical Combinations - Complex targeting using AND/OR logic
  • Maintained membership - Courier keeps each audience’s membership list current as profiles change (pre-computed and rebuilt, not evaluated per send)

​
Static Lists

Lists are manually managed collections of users that you control completely. They’re ideal for curated groups where you want precise control over membership.
List Management Interface

​
API Usage

Target a list using the list_id parameter in your send request: 
{
  "to": {
    "list_id": "beta_testers"
  }
}

​
Dynamic Audiences

Audiences automatically include or exclude users based on rules and filters you define. Instead of manually managing membership, Courier maintains a membership list for each audience based on your rules and profile updates.
Audience Builder Interface

​
API Usage

Target an audience using the audience_id parameter in your send request: 
{
  "to": {
    "audience_id": "active_premium_users"
  }
}

​
Audience Configuration

Audiences use operators to define which user profiles belong in the audience. Those rules drive how Courier builds and refreshes the audience membership list. When you send to an audience, Courier uses that list to choose recipients; it does not re-run the full rule set against every profile at send time. Benefits of dynamic audiences:
  • Automatic updates - Membership changes as user data changes
  • Complex targeting - Combine multiple conditions with logical operators
  • Scalable segmentation - No manual list maintenance required

​
Available Operators

The table below summarizes operators when defining an audience in the UI or API. We’ve included both the operator as shown in the UI and the code value used in the Audiences API.
CategoryOperatorCodeUse Cases
EqualityisEQMatch exact values (subscription tiers, roles, statuses)
is notNEQExclude specific values (not free tier, not inactive)
StringincludesINCLUDESEmail domains, name patterns, job titles
does not includeOMITExclude patterns or keywords
starts withSTARTS_WITHEmail prefixes, ID patterns
ends withENDS_WITHEmail domains (@company.com), file extensions
Numericis greater thanGTAge minimums, spending thresholds
is greater than or equal toGTEAccount limits, minimum values
is less thanLTAge maximums, company size limits
is less than or equal toLTEBudget caps, usage limits
Dateis greater thanAFTERRecent activity, future dates
is less thanBEFOREHistorical data, cutoff dates
ExistenceexistsEXISTSHas premium features, has phone number
MEMBER_OF is not an audience-definition operator. When you need to restrict an audience send to users who belong to a specific tenant, pass it as an inline filter in to.filters on the send rather than in the audience definition.

​
Combining Conditions

Use logical operators to create complex audience rules:
  • AND: All conditions must be true (premium users in California)
  • OR: At least one condition must be true (admin or manager roles)

​
How audience membership works

Courier pre-computes audience membership. When a user profile changes, processing updates whether that user belongs to each audience. When you change an audience’s filter rules, Courier starts a rebuild of the membership list for that audience.
  1. Membership is materialized - At send time, Courier reads from the stored membership for that audience version, not by evaluating every rule against every profile in one synchronous pass.
  2. Rebuilds after filter changes - Rebuilding a large audience can take many minutes (for example 15–20 minutes for very large workspaces). While a rebuild is in progress, sends can read a partially updated membership list.
  3. Best practice before large sends - After changing audience rules, wait for membership to settle. Use GET /audiences/{audience_id} and, if needed, spot-check GET /audiences/{audience_id}/members before you send to the full audience.

​
Scoping audience sends by tenant

context.tenant_id on a send controls branding, preferences, and template variables for that tenant. It does not restrict which users in an audience receive the message. To limit an audience send to users who belong to a specific tenant, add an inline filters array on the audience recipient with the MEMBER_OF operator and path: account_id (tenant id in Courier). Users must have tenant memberships via the User Tenants API (for example PUT /users/{user_id}/tenants/{tenant_id}). 
{
  "message": {
    "to": {
      "audience_id": "my-audience",
      "filters": [
        { "operator": "MEMBER_OF", "path": "account_id", "value": "<tenant_id>" }
      ]
    },
    "template": "TEMPLATE_ID",
    "context": { "tenant_id": "<tenant_id>" }
  }
}
The AudienceFilter schema in the OpenAPI spec documents MEMBER_OF for this use case.

User Management

Individual user profiles and targeting

Audiences API

Create and manage audiences programmatically

Audience Trigger

Start automations when users enter or leave an audience