Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

User profiles store the contact details and attributes Courier needs to deliver notifications. Instead of passing an email address or phone number with every send call, you create a profile once and send to the user by ID. This tutorial covers creating profiles, updating them with new data, storing push tokens, and using profile data in your notifications.

​
Prerequisites

​
Create a User Profile

The Profiles API uses POST /profiles/:user_id to create or merge data into a profile. If the profile already exists, the supplied values are merged with the existing profile.
1

Create a profile with contact details

curl -X POST https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "email": "jane@example.com",
      "phone_number": "+15551234567",
      "name": "Jane Doe",
      "locale": "en_US",
      "custom": {
        "company": "Acme Corp",
        "role": "admin",
        "plan": "premium"
      }
    }
  }'
The user_id in the URL path (user_123) is the unique identifier you’ll use to send notifications to this user. You choose this ID; it can be any string.
2

Verify the profile

curl https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN"
You can also view the profile in the Users section of the Courier dashboard.

​
Update a Profile

There are two update strategies depending on whether you want to merge or fully replace the profile data.

​
Merge Update (POST)

POST /profiles/:user_id merges the supplied values into the existing profile. Existing fields that aren’t included in the request are preserved. 
curl -X POST https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "custom": {
        "plan": "enterprise"
      }
    }
  }'
After this call, email, phone_number, name, and other existing fields are unchanged; only custom.plan is updated.

​
Full Replace (PUT)

PUT /profiles/:user_id replaces the entire profile. Any fields not included in the request are removed. 
curl -X PUT https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "email": "jane.doe@newcompany.com",
      "name": "Jane Doe"
    }
  }'
A PUT replaces the entire profile. After this call, phone_number, locale, custom, and any other fields from the original profile are gone. Use POST for partial updates.

​
Send to a Profile

Once a profile exists, send notifications by user ID instead of specifying contact details inline. 
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "user_id": "user_123"
      },
      "template": "WELCOME_EMAIL",
      "data": {
        "login_url": "https://app.example.com/login"
      }
    }
  }'
Courier looks up the user’s profile, resolves their contact details (email, phone, push tokens), and routes the notification based on channel configuration and user preferences.

​
Inline Profile Overrides

You can override or supplement profile data at send time. The inline values are merged with the stored profile for that specific send without modifying the stored profile. 
{
  "message": {
    "to": {
      "user_id": "user_123",
      "email": "temporary-override@example.com"
    },
    "template": "WELCOME_EMAIL"
  }
}

​
Store Channel Tokens

Push notification providers (FCM, APNS) require device tokens to deliver messages. Store tokens using the Device Tokens API or let Courier SDKs handle it automatically.

​
Via API

curl -X PUT https://api.courier.com/users/user_123/tokens/device_abc \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "fcm_device_token_here",
    "provider_key": "firebase-fcm",
    "device": {
      "app_id": "com.example.myapp",
      "platform": "android"
    }
  }'
Courier’s mobile SDKs handle token registration, refresh, and cleanup automatically: 
// React Native
import { Courier } from "@courier/react-native";

await Courier.setUserId("user_123");
// SDK automatically registers device tokens
For details, see the iOS SDK, Android SDK, or React Native SDK.

​
Use Profile Data in Templates

Any field stored in a user’s profile is available as a template variable. In your notification templates, reference profile fields with the profile prefix. For example, if a profile has: 
{
  "name": "Jane Doe",
  "custom": {
    "company": "Acme Corp"
  }
}
You can use {{profile.name}} and {{profile.custom.company}} in your template content. You can also use {{name}} as a shorthand for top-level profile fields.
Custom attributes stored under the custom key are great for personalization: user roles, subscription tiers, company names, or any data your templates need.

​
Delete a Profile

curl -X DELETE https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN"
Deleting a profile removes all stored data. Notifications sent to this user ID will fail until a new profile is created.

​
What’s Next

User Management

Platform reference for user profiles, CSV import, and push tokens

Profiles API Reference

Full API documentation for profile CRUD operations

Send Your First Message

Get started with the Courier Send API

Configure Preferences

Let users control which notifications they receive