Skip to main content
A list is a group of users you curate. Membership changes only when you change it. Use a list for hand-picked groups: beta testers, a VIP cohort, an internal team. When membership should follow from profile data, use an . Browse lists and their members under , or manage them over the API as below.

​
How it works

Each list has a dotted-namespace list_id such as acme-corp.beta-testers. Target one on a send with list_id:
The manages lists and their members. is an upsert, so it also creates one. The /lists/{list_id}/subscriptions endpoints add, replace, read, and remove members. subscribes one user.

​
List patterns

Because list_id is a dotted namespace, one pattern can target many lists at once. Set list_pattern on the recipient. * matches any single part. ** is a trailing wildcard:
The same pattern syntax filters lists on through its pattern parameter. Naming a list after an entity, such as document.doc_a1b2.watchers, turns this into per-entity subscriptions. walks that pattern end to end.

​
Valid ids and patterns

A list_id holds up to six dot-separated segments. It cannot be empty, include *, #, or a space, start or end with a period, or hold two periods in a row. A wildcard replaces one whole segment, never part of one, so every * follows a period. Courier rejects these patterns:

​
Scoping a list send to a tenant

context.tenant_id controls branding, preferences, and template variables. It does not restrict which list members receive the message. To send only to users in one tenant, add an inline filters array with the MEMBER_OF operator:
Users must have tenant membership, set with , to pass the filter.

​
Limits & behavior

  • List membership is exact and immediate. A member is present the moment you add them. There is no rebuild step and no propagation delay.
  • MEMBER_OF is a send-time filter. Use it inline on the recipient to scope a send by tenant. It is not part of the list definition.

​
FAQ

Use a list when you pick members by hand and want membership exact, like beta testers or VIPs. Use an when membership follows from profile data and should update itself.
Use list_pattern with * for a single part, or ** as a trailing wildcard, to match many list_ids in one send.