Users and profiles

A user is the stored record Courier uses to reach one person. Send by user_id and Courier resolves the addresses. That record is the profile. It holds email, phone number, device tokens, locale, timezone, and custom attributes, so you never repeat contact details on a request. Preferences, lists, and audiences attach to it.

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

Save a user

Creating and updating are the same call, so this is safe to run whenever your own record changes:

await client.profiles.create("user_123", {
  profile: {
    email: "sarah@acme-corp.com",
    phone_number: "+15551234567",
  },
});

client.profiles.create(
    "user_123",
    profile={
        "email": "sarah@acme-corp.com",
        "phone_number": "+15551234567",
    },
)

curl -X POST https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "email": "sarah@acme-corp.com",
      "phone_number": "+15551234567"
    }
  }'

courier.profiles.create(
  "user_123",
  profile: {
    email: "sarah@acme-corp.com",
    phone_number: "+15551234567"
  }
)

_, err := client.Profiles.New(context.TODO(), "user_123", courier.ProfileNewParams{
	Profile: map[string]any{
		"email":        "sarah@acme-corp.com",
		"phone_number": "+15551234567",
	},
})

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"))
        .build())
    .build();

client.profiles().create(params);

$client->profiles->create(
  'user_123',
  profile: [
    'email' => 'sarah@acme-corp.com',
    'phone_number' => '+15551234567',
  ],
);

await client.Profiles.Create(
    "user_123",
    new()
    {
        Profile = new Dictionary<string, JsonElement>
        {
            { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
            { "phone_number", JsonSerializer.SerializeToElement("+15551234567") },
        },
    }
);

courier profiles create user_123 \
  --api-key "$COURIER_API_KEY" \
  --profile '{"email": "sarah@acme-corp.com", "phone_number": "+15551234567"}'

With Courier MCP, save user_123 with the email sarah@acme-corp.com and the phone number +15551234567.

The user_id is yours to choose. Use whatever your own system already calls that person, so you never keep a mapping table.

What each channel needs

One field per channel, and Courier picks the right one per send:

Channel	Field on the profile	Example
Email	`email`	`sarah@acme-corp.com`
SMS	`phone_number`, in E.164	`+15551234567`
WhatsApp	`phone_number`, in E.164	`+15551234567`
Push	none. Device tokens are stored outside the profile	Registered by the or the Token API
Inbox	none. The `user_id` is the address
Chat	the provider’s own object, such as `slack` or `ms_teams`	`{ "access_token": "xoxb-…", "email": "…" }`

A profile holds every field at once. Save email and phone_number together and one template can reach either channel without a second write. Each category introduction carries its own providers’ fields: , , , and .

Send by user id

Once the profile exists, a send names the person and nothing else:

const { requestId } = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40"
    }
  }'

response = courier.send_.message(
  message: {
    to: {user_id: "user_123"},
    template: "nt_01kx4h2jdafq8bk9aftxak4b40"
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
	},
})

SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .template("nt_01kx4h2jdafq8bk9aftxak4b40")
    .build();

client.send().message(SendMessageParams.builder().message(message).build());

$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40

With Courier MCP, send my welcome template to user_123.

Which channel it goes out on is the template’s and ’s decision, not the recipient’s.

Address someone you have not saved

An address in the to object sends with no stored profile. It reaches the recipient and leaves nothing behind, so there is no profile to update later and no preferences to respect. A saved user stays the norm, because preferences, lists, tenants, and the inbox all key off one. Each channel takes its own field or object:

{ "to": { "email": "sarah@acme-corp.com" } }

Every reads this field.

{ "to": { "phone_number": "+15551234567" } }

E.164 only. Every reads it, and reads the same field.

{ "to": { "apn": { "token": "YOUR_APNS_TOKEN" } } }

One key per provider: apn, firebase-fcm, or expo. Each takes a token or a tokens array. See .

{ "to": { "slack": { "access_token": "xoxb-xxxxx", "email": "sarah@acme-corp.com" } } }

Address by email, channel, or user_id, always with the access_token. See .

{ "to": { "ms_teams": { "tenant_id": "YOUR_TEAMS_TENANT_ID", "service_url": "https://smba.trafficmanager.net/amer/", "user_id": "TEAMS_USER_ID" } } }

tenant_id and service_url are always required. Then one of user_id, email, channel_id, channel_name, or conversation_id. See .

{ "to": { "discord": { "channel_id": "DISCORD_CHANNEL_ID" } } }

A channel_id for a channel, or a user_id for a direct message. See .

{ "to": { "webhook": { "url": "https://api.acme-corp.com/courier-events" } } }

Takes method, headers, and an authentication object as well. See .

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

The inbox has no direct form. The user_id is the address, because that is who the SDK signs in as. See .

The two combine. Courier merges an inline value over the saved profile for that message only, so this sends to the override address and never changes the profile:

{ "to": { "user_id": "user_123", "email": "billing@acme-corp.com" } }

When to write a profile

On signup, in the same handler that creates the user in your own database. , , , and each show that call in place. Whenever an address changes. POST merges, so writing one field leaves the rest alone. Not on every send. A profile write per send costs a round trip and buys nothing, because the profile is already there.

The profile object

A profile accepts three kinds of field:

OpenID Connect standard claims. email, phone_number, name, given_name, family_name, locale, zoneinfo, birthdate, and more.
custom. A free-form object for anything specific to your app.
Provider-specific keys. apn, airship, and others, for inline channel tokens.

{
  "profile": {
    "name": "Sarah Bennett",
    "email": "sarah@acme-corp.com",
    "phone_number": "+15551234567",
    "locale": "en-US",
    "custom": {
      "company": "Acme Corp",
      "plan": "business",
      "role": "admin"
    }
  }
}

Every profile field is available in templates. Reference top-level fields as {profile.name} and custom data as {profile.custom.company}.

Merge, replace, or patch

The Profiles API has four operations on /profiles/{user_id}. They differ in what happens to fields you leave out:

Operation	Method	Effect on omitted fields
Merge / create	`POST`	Preserved. Supplied values are merged into the existing profile, or create it.
Replace	`PUT`	Removed. The profile becomes exactly what you send.
Patch	`PATCH`	Untouched. Applies a list of JSON-patch operations (`op`, `path`, `value`).
Delete	`DELETE`	The whole profile is removed.

Use POST for everyday updates so you never drop data. Use PUT only for a deliberate full overwrite. The Node SDK names these profiles.create, profiles.replace, profiles.update for patch, and profiles.delete.

Device tokens

Push reaches a device, not an address, so a user carries a device token per device they sign in on. The Courier mobile SDKs register and refresh those tokens for you, on iOS, Android, Flutter, and React Native. walks the whole thing: a provider, the SDK, and a test push to your own device. Tokens attach to the user_id rather than to the profile body, so Courier expires a dead one without touching the profile. A backend that manages tokens itself writes them with the .

Limits & behavior

A send resolves an existing profile, it does not create one. To reach a user by user_id, save the profile first or include inline contact details on that send. In-app recipients are the exception. Signing a user in to the Inbox registers them, so you can send to a user who exists only through .
No endpoint lists every user. You retrieve profiles one at a time by known user_id. Keep your own system of record as the source of truth.
custom is free-form, standard claims are typed. Store app-specific data under custom. Courier accepts top-level keys outside the OIDC claim set, but they are clearest in custom.
No documented rate limit on the Profiles API. The , but profile reads and writes have no published per-second cap. For a large sync, throttle your loop or import a CSV in the console.
Device tokens are not part of the profile body. Writing a profile with PUT does not remove stored device tokens.

FAQ

What should I use for the user_id?

The id your own system already uses for that person. Courier accepts any string, so matching your database means no mapping table and no second lookup.

Does sending to a new user_id create the profile?

A send looks up an existing profile, it does not persist one from the to object. Create the profile with first, or pass inline contact details for a one-off. The Inbox is the exception. Authenticating a user registers them.

Does saving a profile twice create two users?

user_id is the key, so a second write to the same id updates that user. is an upsert.

Can one user hold email, phone, and a Slack token at once?

One profile holds every address at once, which is the point. Save every address you have and the same send reaches whichever channel the template and pick.

Where do push device tokens get saved?

The mobile SDKs register them on signIn, or your backend writes them with . Either way they attach to the user_id rather than to the profile body. See .

Can I export or dump all of my users?

Courier has no endpoint to list every user_id, export all profiles, or return a total user count. Retrieve profiles one at a time with . List the users in one tenant with .

Is 'recipient' the same as 'user'?

Courier uses them interchangeably. A recipient identified by user_id is a stored user profile.

What is the difference between POST and PUT on a profile?

POST merges, so fields you omit are preserved. PUT replaces, so the profile becomes exactly the object you send and omitted fields are removed. Use POST for partial updates, PUT only for a deliberate full overwrite.

How do I store data that is not an OIDC claim?

Put it under custom. It is free-form, and every key is available in templates as {profile.custom.plan}.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Users and profiles

Save a user

What each channel needs

Send by user id

Address someone you have not saved

When to write a profile

The profile object

Merge, replace, or patch

Device tokens

Limits & behavior

FAQ

​Save a user

​What each channel needs

​Send by user id

​Address someone you have not saved

​When to write a profile

​The profile object

​Merge, replace, or patch

​Device tokens

​Limits & behavior

​FAQ

Save a user

What each channel needs

Send by user id

Address someone you have not saved

When to write a profile

The profile object

Merge, replace, or patch

Device tokens

Limits & behavior

FAQ