User Management

​

Overview

​

Key Features

• User Profiles - Store contact details, preferences, and custom attributes through UI and API
• Multi-Tenant Architecture - Organize users into tenants for B2B SaaS platforms
• Push Token Management - Automatic device token handling for mobile notifications
• Profile Customization - Add custom attributes for personalized messaging

​

Creating Users

• Add contact information (email, phone, etc.)
• Set custom attributes
• Configure initial preferences
• Assign to tenants

{
  "profile": {
    "email": "user@example.com",
    "phone_number": "+1234567890",
    "custom": {
      "name": "John Doe",
      "subscription_tier": "premium",
      "company": "Acme Corp",
      "role": "admin"
    }
  }
}

​

Importing Users via CSV

​

How to Import

1. Navigate to Users in the left sidebar
2. Click the Import button
3. Download the CSV template using the link in the import dialog
4. Add your user data to the downloaded template
5. Upload the populated CSV file
6. Click Add Users to create the profiles

​

CSV Format Requirements

• Delimiter: Commas (,). The file must be comma-separated.
• Encoding: UTF-8 without BOM. Do not use UTF-16 or UTF-8 with BOM.
• Header row: Must match the template exactly. Do not rename, reorder, or add columns.
• Quoting: Values containing commas should be wrapped in double quotes. Empty fields should use "".
• Trailing newline: The file must not end with a blank line after the last row of data. A trailing newline causes the parser to interpret the empty final line as a data row with one field, triggering a “Too few fields” error.

​

Template Fields

​

Creating a CSV File from a Text Editor

1. Open a new file in your text editor
2. Paste the header row from the template (or copy it from below)
3. Add one data row per user, matching the 22 fields exactly
4. Save the file as UTF-8 with a .csv extension
5. Make sure there is no blank line after your last row of data

"id","name","first_name","last_name","email","phone_number","gender","birthdate","zoneinfo","locale","given_name","family_name","middle_name","nickname","preferred_username","profile","picture","website","email_verified","phone_number_verified","sub","courier.channel"
"user_001","Jane Doe","Jane","Doe","jane@example.com","","","","","","","","","","","","","","","","",""

​

Known Spreadsheet Pitfalls

• Encoding changes: Excel’s “Export” function can produce UTF-16 files instead of UTF-8. Always use Save As > CSV (Comma delimited) rather than Export. If you’re unsure, open the saved file in a text editor and verify it looks like readable plain text.
• Delimiter substitution: In European and some other locales, Excel uses semicolons (;) instead of commas as the CSV delimiter. Check your file in a text editor after saving. If you see semicolons between fields, switch Excel’s list separator in your system settings or create the file in a text editor instead.
• Extra columns: Excel sometimes adds trailing empty columns when re-saving. The template has 22 fields; if your header has more, the importer will expect that many fields in every row. Open the file in a text editor and remove any extra commas at the end of the header row.
• Re-saving overwrites fixes: If you fix a CSV in a text editor and then re-open and save it in Excel, Excel may reintroduce the same encoding or delimiter issues. After fixing a file in a text editor, upload it directly without opening it in a spreadsheet application again.

​

Troubleshooting CSV Import

• Wrong delimiter: Open in a text editor and check whether fields are separated by commas. If you see semicolons or tabs, re-save as CSV (Comma delimited).
• Wrong encoding: If the file contents look garbled in a text editor (unusual characters, ÿþ at the start, or double-spaced letters like "i","d"), the file is likely UTF-16. Re-create the file in UTF-8, or copy and paste the contents into a new text file and save as UTF-8.
• BOM marker: A UTF-8 BOM (EF BB BF) at the start of the file can occasionally interfere with header parsing. If you see  before the first field in a text editor, remove those characters.

​

User Profile Management

​

Direct Address Targeting

{
  "to": {
    "email": "user@example.com"
  }
}

​

Profile-Based Targeting

{
  "to": {
    "user_id": "user_123"
  }
}

• Flexible routing - Channel selection based on user preferences and routing rules
• Personalization - Access user attributes for dynamic content
• Preference management - Users control their notification channels and frequency
• Data persistence - User information persists across notifications

​

Multi-Tenant Support

{
  "to": {
    "user_id": "user_123",
    "context": {
      "tenant_id": "company_abc"
    }
  }
}

​

Push Notification Setup

​

Device Token Management

• Registration: When a user installs your app
• Updates: When tokens change or refresh
• Cleanup: When users uninstall or switch devices

​

Push Message Targeting

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

​

SDK-Based Token Management (Recommended)

// React Native example
import { Courier } from '@courier/react-native';

// SDK automatically handles token generation and refresh
await Courier.setUserId('user_123');

• Automatic token generation and refresh
• Device registration handling
• Cross-platform support (iOS, Android, React Native)
• Error handling and retries
• Background sync

​

Manual Token Management

{
  "token": "device_token_from_firebase",
  "provider_key": "firebase-fcm"
}

• Custom token handling logic
• Legacy app integration without SDK support
• Specific provider requirements not covered by SDKs

​

Related Resources