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.

  • part1

  • part1.part2

  • part1.part2.spart3

  • part1.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:

  • pokemon

  • pokemon.type

  • pokemon.type.generation

  • pokemon.type.generation.evolution

So a list of List IDs following this pattern could be:

  • pokemon

  • pokemon.grass


  • pokemon.grass.gen1

  • pokemon.grass.gen2



  • pokemon.grass.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 would only send to the unique users subscribed to these exact Lists:

  • pokemon.grass.gen1



pokemon.grass.* would only send to the unique users subscribed to these exact Lists:

  • pokemon.grass.gen1

  • pokemon.grass.gen2**

pokemon.grass.** would only send to the unique users subscribed to these exact Lists:





While pokemon.** would send to every unique user subscribed to any List below pokemon.

  • pokemon.grass


  • pokemon.grass.gen1

  • pokemon.grass.gen2



  • pokemon.grass.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 name would be invalid while, list_name would be valid.

  • List IDs may not include more than four parts. ie root_part.part.part.part.part etc. 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.part List Pattern cannot include spaces.

  • part.*** : List Pattern cannot include more than two consecutive asterisks.

  • poke** ,* : The wildcard (*) or (**) must replace the entire part name within the List pattern.

Did this answer your question?