Users

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.

Inline

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

"to": {
    "email": "luke@skywalker.com"
}

Profiles

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"
}

Lists

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"
}

Audiences

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"
}

Tenants

Courier support multi-tenant applications with the Tenants API. A single user can be associated with multiple tenants, and you can specify a tenant_id when sending a message in order to ensure the correct preferences and configuration values are applied.

"to": {
    "user_id": "luke1234",
    "context": {
        "tenant_id" : "red-squadron"
    }
}

You can also send message to all of the users in a tenant.

"to": {
    "tenant_id" : "red-squadron"
}

Tokens

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": [
            "push"
        ]
    }
}

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.