Skip to main content

​
Overview

Courier provides flexible ways to define who receives notifications - from simple email addresses to sophisticated user segmentation. Understanding these targeting methods helps you build scalable notification systems that grow with your application. You may see the term “recipient” used interchangeably with “user” - they mean the same thing.

​
Key Features

Courier’s user management provides complete control over individual user profiles and targeting:
  • User Profiles - Store contact details, preferences, and custom attributes through UI and API
  • Multi-Tenant Architecture - Support organizational hierarchies for B2B SaaS platforms
  • Push Token Management - Automatic device token handling for mobile notifications
  • Profile Customization - Add custom attributes for personalized messaging

​
Creating Users

User Creation Interface
Create users directly in the Courier platform or through the API. The platform interface allows you to:
  • Add contact information (email, phone, etc.)
  • Set custom attributes
  • Configure initial preferences
  • Assign to tenants
Sample API request for user creation: 
{
  "user_id": "user_123",
  "profile": {
    "email": "[email protected]",
    "phone_number": "+1234567890",
    "custom": {
      "name": "John Doe",
      "subscription_tier": "premium",
      "company": "Acme Corp",
      "role": "admin"
    }
  }
}

​
User Profile Management

​
Direct Address Targeting

The code samples below illustrate a subset of the message object used to make a call to the send API.
For simple use cases, specify email addresses or phone numbers directly in API calls: 
{
  "to": {
    "email": "[email protected]"
  }
}

​
Profile-Based Targeting

User profiles store recipient information including contact details, preferences, and custom attributes. This approach separates user data from sending logic, enabling better personalization and routing flexibility. 
{
  "to": {
    "user_id": "user_123"
  }
}
Benefits:
  • Flexible routing: Channel selection happens based on user preferences and routing rules
  • Personalization: Access to user attributes for dynamic content
  • Preference management: Users can control notification channels and frequency
  • Data persistence: User information stored for future notifications
Profile structure example: 
{
  "user_id": "user_123",
  "email": "[email protected]",
  "phone_number": "+1234567890",
  "preferences": {
    "channels": ["email", "push"]
  },
  "custom_attributes": {
    "name": "John Doe",
    "subscription_tier": "premium"
  }
}
User Custom Attributes
For more on programmatic profile management, see the Profiles API Documentation.

​
Multi-Tenant Support

For B2B SaaS platforms, Courier supports organizational hierarchies through tenants. Users can belong to multiple tenants with different preferences and branding for each context. 
{
  "to": {
    "user_id": "user_123"
  },
  "tenant_id": "company_abc"
}
Tenants provide scoped preferences, custom branding, and hierarchical structures. For comprehensive tenant functionality including tenant hierarchies, inheritance, and advanced features, see the Tenants Documentation.

​
Push Notification Setup

Push notifications require device tokens that link users to their mobile devices. Courier provides both manual and automatic token management approaches.

​
Device Token Management

Device tokens are unique identifiers that allow push notification providers (FCM, APNS) to deliver messages to specific devices. Courier manages these tokens and associates them with user profiles. Token lifecycle:
  • Registration: When a user installs your app
  • Updates: When tokens change or refresh
  • Cleanup: When users uninstall or switch devices

​
Push Message Targeting

Once tokens are configured, target users for push notifications: 
{
  "message": {
    "to": {
      "user_id": "user_123"
    },
    "content": {
      "title": "Your order is ready!",
      "body": "Pick up your order at the nearest location."
    },
    "routing": {
      "method": "single",
      "channels": ["push"]
    }
  }
}
The system automatically uses the appropriate device tokens based on the user’s registered devices and your configured push providers. There are two ways to configure tokens. Use Courier SDKs for automatic token handling: 
// React Native example
import { Courier } from '@courier/react-native';

// SDK automatically handles token generation and refresh
await Courier.setUserId('user_123');
SDK benefits:
  • Automatic token generation and refresh
  • Device registration handling
  • Cross-platform support (iOS, Android, React Native)
  • Error handling and retries
  • Background sync

​
Manual Token Management

Not Recommended: Manual token management requires handling token refresh, rotation, and validity yourself. Use Courier SDKs for automatic token management instead.
For edge cases requiring direct token control, use the Token Management API: 
{
  "user_id": "user_123",
  "provider_key": "firebase-fcm",
  "token": "device_token_from_firebase",
  "properties": {
    "device_id": "abc123",
    "app_version": "1.2.3"
  }
}
When you might need manual management:
  • Custom token handling logic
  • Legacy app integration without SDK support
  • Specific provider requirements not covered by SDKs

Lists & Audiences

Group targeting and segmentation

Profiles API

User profile management reference