Skip to main content


Courier uses the term user to describe the recipient of a notification. You'll sometimes see the term recipient used, but these mean the same thing. There are several different ways to define which users will recieve a notification.

The code samples below illustrate a subset of the message object used to make a call to the send API.


The simplest way to send a notification is to specify either an email or a phone_number.

"to": {
"email": ""


Courier supports storing user contact information in a Profile record, and then referencing a user_id when calling send. One of the benefits of this approach is that the specific channel that is used to deliver the notification can be deferred to a later step where routing rules are applied.

"to": {
"user_id": "luke1234"


If you want to send a notification to more than one user, you can add as many users as you like to a List and then pass the list_id.

"to": {
"list_id": "rebel-alliance"


Instead of using a static list of users, you can create an Audience that will dynamically include users based on their attributes and a set of custom filtering rules that you define.

"to": {
"audience_id": "currently-on-hoth"


Courier has a hierarchical database object called Tenants that maps to use cases like workspaces, organizations, projects, groups, and/or roles within your application. Users can belong to zero to many tenants, have preferences based on tenants, and separate Inbox's.

See the Tenants Documentation or API for usage. A single user can be associated with multiple tenants, and you can specify a tenant_id when sending a message to ensure the correct preferences and configuration values are applied.


When sending push notifications to mobile devices, developers need to create tokens that are mapped to the users they are sending notifications to.

Once you create a token and attach it to a user and provider, you do not need to include it in the call to the Send API when you send a push notification.

"message": {
"to": {
"user_id": "luke1234",
"content": {
"title": "Where do Sith go shopping?",
"body": "At the Darth Maul!"
"routing": {
"method": "single",
"channels": [

Additionally, if you use use the Courier client SDK libraries in your mobile application, they will automatically handle token generation and rotation for you automatically, so you won't need to handle token management in your code.