The Courier Lists API lets you create Lists and associate one or more recipients with them in the Courier database.
Why use Lists?
Many times there are groups of users you want to message with the same notification triggered by the same event. In the past, this meant tens or sometimes thousands of API calls, triggering the same notification over and over. With Courier’s Lists API, you’re able to create lists, subscribe recipient profiles to them and send to every user on the list with a single Send API call.
When you send to a list, Courier handles the message fanout–following user preferences and your channel priorities–to deliver across Push, Email, SMS, Messaging Apps, and more.
With the Lists API, you can easily do things like:
Reach every user in a shared workspace.
Notify all users who follow a specific project.
Alert users subscribed to a feature flag
Message users who opt in to select notifications.
What are Lists and Lists Patterns?
A List usually represents some kind object in your system. Once you've created a List, you can send a message to all the recipients you subscribed to that List with a single Send API call (Courier handles the fan-out).
When naming your Courier Lists, we recommend you follow our List Pattern guidelines. Using this pattern will allow you to use wildcarding to send to multiple Lists with a single Send API call.
Understanding and defining List ID Patterns
Courier supports List IDs with up to four parts to enable wildcard sending.
Thinking about how to structure your List IDs according to Courier's List pattern support (up to 4 parts in a List) will allow you to send to multiple List parts within a related pattern using a single API call.
Follow this basic pattern when defining List IDs.
part1part1.part2part1.part2.spart3part1.part2.part3.part4
Important: Each ID string is its own List. If you provide part1.part2 as the List id when creating a List, that's a single List with the id of part1.part2
Subscribing a user to part1.part2 does not automatically subscribe users to part1 or List parts above it as well. You need to subscribe users to every List or List part that should apply to that user.
As an example, let's apply this relational pattern to Pokémon:
pokemonpokemon.typepokemon.type.generationpokemon.type.generation.evolution
So a list of List IDs following this pattern could be:
pokemonpokemon.grasspokemon.firepokemon.grass.gen1pokemon.grass.gen2pokemon.fire.gen1pokemon.fire.gen2pokemon.grass.gen1.evolution1pokemon.fire.gen1.evolution1
Using Patterns and wildcards to send to multiple Lists at a time
Following this four-part List pattern allows you to send to more than one List at the same time by using wildcards. You can wildcard up to 3 of the 4 parts within a List pattern.
Using a single asterisk
*will wild card every List within that part.Using a double asterisk
**will wild card every List in every part that follows the first part. IE it's like saying "all List that start with".
Here are a few wildcard examples using our Pokemon Lists:
pokemon.*.gen1
pokemon.*.gen1 would only send to the unique users subscribed to these exact Lists:
pokemon.grass.gen1pokemon.fire.gen1
pokemon.grass.*
pokemon.grass.* would only send to the unique users subscribed to these exact Lists:
pokemon.grass.gen1pokemon.grass.gen2
pokemon.fire.**
pokemon.grass.** would only send to the unique users subscribed to these exact Lists:
pokemon.fire.gen1pokemon.fire.gen2pokemon.fire.gen1.evolution1
pokemon.**
While pokemon.** would send to every unique user subscribed to any List below pokemon.
pokemon.grasspokemon.firepokemon.grass.gen1pokemon.grass.gen2pokemon.fire.gen1pokemon.fire.gen2pokemon.grass.gen1.evolution1pokemon.fire.gen1.evolution1
Invalid Lists, List Patterns and Wildcards
The following are examples of invalid List IDs, Patterns and wildcarding that Courier List and Patterns do not support.
Invalid List IDs:
Empty strings.
List IDs may not include
*or#in the in the name.List IDs my not start or end with a period
.or include consecutive periods..List IDs may not include spaces ex:
list namewould be invalid while,list_namewould be valid.List IDs may not include more than four parts. ie
root_part.part.part.part.partetc. would be invalid.
Examples of Invalid List Patterns and wildcards
**: List Patterns cannot match all Lists. It is not possible to send to all Lists using wildcards, so sending a request with only (**) will fail.**.part: List Pattern cannot include a starts with (**) anywhere but at the end.*.**: List Pattern cannot include an asterisk (*) followed by asterisks (**)part.*.: List Pattern cannot end with a period (.)..part.part: List Pattern cannot start with a period (.)...part.*:List Pattern cannot include consecutive periods (..).part .part.partList Pattern cannot include spaces.part.***: List Pattern cannot include more than two consecutive asterisks.poke**,pokemon.fire.g*: The wildcard (*) or (**) must replace the entirepartname within the List pattern.