Import your users

Get your users into Courier so a send only needs their user_id. A profile stores one person’s contact details. Load profiles from a CSV or your own database, then update them as your system of record changes. covers one profile and the field each channel reads. This guide is the same call at the scale of your whole user table.

Prerequisites

The examples assume a client initialized once with your key from the environment:

import Courier from '@trycourier/courier';

const client = new Courier({
  apiKey: process.env['COURIER_API_KEY'],
});

import os

from courier import Courier

client = Courier(
    api_key=os.environ.get("COURIER_API_KEY"),
)

export COURIER_API_KEY="YOUR_COURIER_API_KEY"

require "courier"

courier = Courier::Client.new(api_key: ENV["COURIER_API_KEY"])

client := courier.NewClient(
	option.WithAPIKey(os.Getenv("COURIER_API_KEY")),
)

CourierClient client = CourierOkHttpClient.fromEnv();

$client = new Client(apiKey: getenv('COURIER_API_KEY'));

CourierClient client = new();

export COURIER_API_KEY="YOUR_COURIER_API_KEY"

Create or update a profile

Creating and updating are the same call. merges the values you send into the profile, creating it if it does not exist and keeping any fields you leave out. The user_id in the path is the identifier you send to. You choose it.

const profile = await client.profiles.create('user_123', {
  profile: {
    email: 'sarah@acme-corp.com',
    phone_number: '+15551234567',
    name: 'Sarah Bennett',
    locale: 'en-US',
    custom: { company: 'Acme Corp', plan: 'business' },
  },
});

profile = client.profiles.create(
    user_id="user_123",
    profile={
        "email": "sarah@acme-corp.com",
        "phone_number": "+15551234567",
        "name": "Sarah Bennett",
        "locale": "en-US",
        "custom": {"company": "Acme Corp", "plan": "business"},
    },
)

curl --request POST \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "email": "sarah@acme-corp.com",
      "phone_number": "+15551234567",
      "name": "Sarah Bennett",
      "locale": "en-US",
      "custom": { "company": "Acme Corp", "plan": "business" }
    }
  }'

profile = courier.profiles.create(
  "user_123",
  profile: {
    email: "sarah@acme-corp.com",
    phone_number: "+15551234567",
    name: "Sarah Bennett",
    locale: "en-US",
    custom: {company: "Acme Corp", plan: "business"}
  }
)

profile, err := client.Profiles.New(
	context.TODO(),
	"user_123",
	courier.ProfileNewParams{
		Profile: map[string]any{
			"email":        "sarah@acme-corp.com",
			"phone_number": "+15551234567",
			"name":         "Sarah Bennett",
			"locale":       "en-US",
			"custom": map[string]any{
				"company": "Acme Corp",
				"plan":    "business",
			},
		},
	},
)

ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .putAdditionalProperty("phone_number", JsonValue.from("+15551234567"))
        .putAdditionalProperty("name", JsonValue.from("Sarah Bennett"))
        .putAdditionalProperty("locale", JsonValue.from("en-US"))
        .putAdditionalProperty("custom", JsonValue.from(Map.of("company", "Acme Corp", "plan", "business")))
        .build())
    .build();
ProfileCreateResponse profile = client.profiles().create(params);

$profile = $client->profiles->create('user_123', profile: [
  'email' => 'sarah@acme-corp.com',
  'phone_number' => '+15551234567',
  'name' => 'Sarah Bennett',
  'locale' => 'en-US',
  'custom' => ['company' => 'Acme Corp', 'plan' => 'business'],
]);

ProfileCreateParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
        { "phone_number", JsonSerializer.SerializeToElement("+15551234567") },
        { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        { "locale", JsonSerializer.SerializeToElement("en-US") },
        { "custom", JsonSerializer.SerializeToElement(new { company = "Acme Corp", plan = "business" }) },
    },
};
var profile = await client.Profiles.Create(parameters);

courier profiles create \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"email":"sarah@acme-corp.com","phone_number":"+15551234567","name":"Sarah Bennett","locale":"en-US","custom":{"company":"Acme Corp","plan":"business"}}'

With Courier MCP, create a profile for user_123 with their email, phone number, and name.

Device tokens are managed separately.
Push device tokens live on the user, but go through their own API, not the profile body. See to register them.

Read the profile back

Fetch the profile and confirm the stored fields, or open the user in :

const profile = await client.profiles.retrieve('user_123');

profile = client.profiles.retrieve("user_123")

curl --request GET \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY"

profile = courier.profiles.retrieve("user_123")

profile, err := client.Profiles.Get(context.TODO(), "user_123")

ProfileRetrieveResponse profile = client.profiles().retrieve("user_123");

$profile = $client->profiles->retrieve('user_123');

ProfileRetrieveParams parameters = new() { UserID = "user_123" };
var profile = await client.Profiles.Retrieve(parameters);

courier profiles retrieve \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123

With Courier MCP, show me the stored profile for user_123.

Replace instead of merge

Use POST for everyday updates so you never drop data. Use PUT when the profile should become exactly what you send, dropping any field you omit.

const response = await client.profiles.replace('user_123', {
  profile: { email: 'sarah@acme-corp.com', name: 'Sarah Bennett' },
});

response = client.profiles.replace(
    user_id="user_123",
    profile={
        "email": "sarah@acme-corp.com",
        "name": "Sarah Bennett",
    },
)

curl --request PUT \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "email": "sarah@acme-corp.com",
      "name": "Sarah Bennett"
    }
  }'

response = courier.profiles.replace(
  "user_123",
  profile: {email: "sarah@acme-corp.com", name: "Sarah Bennett"}
)

response, err := client.Profiles.Replace(
	context.TODO(),
	"user_123",
	courier.ProfileReplaceParams{
		Profile: map[string]any{
			"email": "sarah@acme-corp.com",
			"name":  "Sarah Bennett",
		},
	},
)

ProfileReplaceParams params = ProfileReplaceParams.builder()
    .userId("user_123")
    .profile(ProfileReplaceParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .putAdditionalProperty("name", JsonValue.from("Sarah Bennett"))
        .build())
    .build();
ProfileReplaceResponse response = client.profiles().replace(params);

$response = $client->profiles->replace('user_123', profile: [
  'email' => 'sarah@acme-corp.com',
  'name' => 'Sarah Bennett',
]);

ProfileReplaceParams parameters = new()
{
    UserID = "user_123",
    Profile = new Dictionary<string, JsonElement>()
    {
        { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
        { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
    },
};
var response = await client.Profiles.Replace(parameters);

courier profiles replace \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123 \
  --profile '{"email":"sarah@acme-corp.com","name":"Sarah Bennett"}'

With Courier MCP, replace user_123's profile with just their email and name.

Replacing removes omitted fields.
After a PUT, any field not in the request (a phone_number, a custom value) is gone. Use POST unless you intend a full overwrite. To change one field, use PATCH with a JSON-patch operation.

Import users from a CSV

For a one-time load or an occasional top-up, import a CSV in the console. There is no CSV API. To load users programmatically, call the profile endpoints above for each user.

Open the importer

Go to and click Import. Download the CSV template from the dialog so your columns match exactly.

Fill in the template

Only id is required. Keep the header row exactly as the template provides it: do not rename, reorder, or add columns. Columns include id, name, first_name, last_name, email, phone_number, locale, zoneinfo, and the OIDC standard claims.

Save as UTF-8 CSV and upload

Save as CSV (comma delimited), UTF-8 without a BOM, and with no blank line after the last row. Upload the file and click Add Users to create the profiles.

Fixing a 'Too few fields' import error

This error means the parser read a row as a single field, almost always a delimiter, encoding, or trailing-line problem:

Wrong delimiter. Open the file in a plain text editor. If fields are separated by semicolons or tabs (some spreadsheet locales use semicolons), re-save as CSV (comma delimited).
Wrong encoding. Garbled characters or ÿþ at the start mean the file is UTF-16. Recreate it as UTF-8. A UTF-8 BOM (ï»¿ before the first field) can also interfere. Remove it.
Trailing blank line. A “Too few fields” error on the last row only usually means an empty final line. Delete any blank lines after the last data row.
Extra columns. If the expected field count is higher than the template’s, your header has extra trailing commas. Remove them.

The most reliable fix is to build the CSV in a plain text editor rather than a spreadsheet app.

Delete a profile

Deleting a profile removes all of its stored data. Sends to that user_id fail until a new profile exists.

await client.profiles.delete('user_123');

client.profiles.delete("user_123")

curl --request DELETE \
  --url https://api.courier.com/profiles/user_123 \
  --header "Authorization: Bearer $COURIER_API_KEY"

courier.profiles.delete("user_123")

err := client.Profiles.Delete(context.TODO(), "user_123")

client.profiles().delete("user_123");

$client->profiles->delete('user_123');

ProfileDeleteParams parameters = new() { UserID = "user_123" };
await client.Profiles.Delete(parameters);

courier profiles delete \
  --api-key "$COURIER_API_KEY" \
  --user-id user_123

With Courier MCP, delete the profile for user_123.

Verify

Read one profile back

Fetch a profile you just wrote and confirm every field you sent is there, spelled the way your templates expect.

Send to the user_id alone

Send a message addressed only by user_id, with no inline profile. Courier resolves the contact details from storage, which proves the import landed.

Check the count after a CSV import

Open and confirm the number of profiles matches your file’s row count. A short count usually means rows the parser rejected.

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Import your users

Prerequisites

Create or update a profile

Import users from a CSV

Delete a profile

Verify

​Prerequisites

​Create or update a profile

​Import users from a CSV

​Delete a profile

​Verify

Prerequisites

Create or update a profile

Import users from a CSV

Delete a profile

Verify