> ## 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. # Subscribe a user Profile to a List > Subscribes one user to a list, creating the list if it does not yet exist. Optional preferences apply to this subscription only. ## OpenAPI ````yaml /openapi-specs/openapi.documented.yml put /lists/{list_id}/subscriptions/{user_id} openapi: 3.0.1 info: title: Courier description: The Courier REST API for sending and managing notifications across channels. version: 0.0.1 servers: - url: https://api.courier.com description: Production security: [] tags: - name: Send description: >- Send a message to one or more recipients — users, lists, audiences, or tenants — across every channel you have configured. - name: Templates description: >- Create, update, version, publish, and localize notification templates and their content. - name: Brands description: >- Manage the logos, colors, and layout that give the templates you send a consistent look. - name: Routing Strategies description: >- Define reusable channel routing and failover strategies, and see which templates use them. - name: Journeys description: >- Build, version, publish, invoke, and cancel multi-step notification workflows, along with the templates scoped to them. - name: Broadcasts description: >- Create a one-off send to a list or audience, author its content, then send it immediately or schedule it for later. - name: User Profiles description: >- Store the contact information Courier delivers to for each user — email, phone number, push tokens, and any custom data you send to. - name: Tenants description: >- Manage tenants — the organizations, teams, or accounts your users belong to — along with their users and default preferences. - name: Audiences description: >- Define filter-based groups whose membership Courier recalculates as user profiles change. - name: Lists description: >- Manage static groups of users that you subscribe explicitly, and send to them by list id or list pattern. - name: Providers description: >- Configure the channel providers Courier delivers through, and browse the provider types it supports. - name: Preference Topics description: >- Manage the workspace catalog of subscription topics, the sections that group them, and publishing the preference page. - name: User Preferences description: >- Read and write a single user's notification preferences, per topic and per channel. - name: Messages description: >- Look up the messages Courier has accepted, inspect their delivery history and rendered output, and cancel, resend, or archive them. - name: Device Tokens description: >- Register and manage the APNS and FCM device tokens Courier delivers push notifications to. - name: Tenant Memberships description: >- Associate a user with one or more tenants, and read or remove those associations. - name: Tenant Templates description: >- Manage the templates and template versions scoped to a single tenant, including the ones authored in the embedded designer. - name: Automations description: >- Invoke a stored automation template or an ad hoc automation defined in the request. - name: Digests description: >- Inspect what has accumulated in a digest schedule and release a digest ahead of its next scheduled delivery. - name: Translations description: >- Store and retrieve the translation strings Courier uses to render localized template content. - name: Track Events description: >- Record an inbound event that triggers the journeys and automations mapped to it. - name: Audit Events description: >- Read the audit trail of configuration and access changes in your workspace. - name: Authentication description: >- Issue scoped, short-lived JWTs so client-side SDKs — Inbox, Preferences, and the embedded designer — can call Courier as a single user. Server-side requests authenticate with your workspace API key instead. paths: /lists/{list_id}/subscriptions/{user_id}: put: tags: - Lists summary: Subscribe a user Profile to a List description: >- Subscribes one user to a list, creating the list if it does not yet exist. Optional preferences apply to this subscription only. operationId: lists_subscribe parameters: - name: list_id in: path description: A unique identifier representing the list you wish to retrieve. required: true schema: type: string - name: user_id in: path description: >- A unique identifier representing the recipient associated with the list required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: preferences: $ref: '#/components/schemas/RecipientPreferences' nullable: true examples: Example: value: preferences: notifications: nt_01kx4h2jdafq8bk9aftxak4b40: status: OPTED_IN responses: '204': description: '' security: - BearerAuth: [] x-codeSamples: - lang: JavaScript source: |- import Courier from '@trycourier/courier'; const client = new Courier({ apiKey: process.env['COURIER_API_KEY'], // This is the default and can be omitted }); await client.lists.subscriptions.subscribeUser('user_id', { list_id: 'list_id', preferences: { notifications: { nt_01kx4h2jdafq8bk9aftxak4b40: { status: 'OPTED_IN' } } }, }); - lang: Python source: |- import os from courier import Courier client = Courier( api_key=os.environ.get("COURIER_API_KEY"), # This is the default and can be omitted ) client.lists.subscriptions.subscribe_user( user_id="user_id", list_id="list_id", preferences={ "notifications": { "nt_01kx4h2jdafq8bk9aftxak4b40": { "status": "OPTED_IN" } } }, ) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/trycourier/courier-go/v4\"\n\t\"github.com/trycourier/courier-go/v4/option\"\n\t\"github.com/trycourier/courier-go/v4/shared\"\n)\n\nfunc main() {\n\tclient := courier.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.Lists.Subscriptions.SubscribeUser(\n\t\tcontext.TODO(),\n\t\t\"user_id\",\n\t\tcourier.ListSubscriptionSubscribeUserParams{\n\t\t\tListID: \"list_id\",\n\t\t\tPreferences: shared.RecipientPreferencesParam{\n\t\t\t\tNotifications: map[string]shared.NotificationPreferenceDetailsParam{\n\t\t\t\t\t\"nt_01kx4h2jdafq8bk9aftxak4b40\": {\n\t\t\t\t\t\tStatus: shared.PreferenceStatusOptedIn,\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n" - lang: Java source: >- package com.courier.example; import com.courier.client.CourierClient; import com.courier.client.okhttp.CourierOkHttpClient; import com.courier.models.lists.subscriptions.SubscriptionSubscribeUserParams; public final class Main { private Main() {} public static void main(String[] args) { CourierClient client = CourierOkHttpClient.fromEnv(); SubscriptionSubscribeUserParams params = SubscriptionSubscribeUserParams.builder() .listId("list_id") .userId("user_id") .build(); client.lists().subscriptions().subscribeUser(params); } } - lang: Ruby source: >- require "courier" courier = Courier::Client.new(api_key: "My API Key") result = courier.lists.subscriptions.subscribe_user("user_id", list_id: "list_id") puts(result) - lang: PHP source: >- lists->subscriptions->subscribeUser( 'user_id', listID: 'list_id', preferences: [ 'categories' => [ 'foo' => [ 'status' => PreferenceStatus::OPTED_IN, 'channelPreferences' => [ ['channel' => ChannelClassification::DIRECT_MESSAGE] ], 'rules' => [['until' => 'until', 'start' => 'start']], ], ], 'notifications' => [ 'nt_01kx4h2jdafq8bk9aftxak4b40' => [ 'status' => PreferenceStatus::OPTED_IN, 'channelPreferences' => [ ['channel' => ChannelClassification::DIRECT_MESSAGE] ], 'rules' => [['until' => 'until', 'start' => 'start']], ], ], ], ); var_dump($result); } catch (APIException $e) { echo $e->getMessage(); } - lang: C# source: |- using TryCourier; using TryCourier.Models.Lists.Subscriptions; CourierClient client = new(); SubscriptionSubscribeUserParams parameters = new() { ListID = "list_id", UserID = "user_id", }; await client.Lists.Subscriptions.SubscribeUser(parameters); - lang: CLI source: |- courier lists:subscriptions subscribe-user \ --api-key 'My API Key' \ --list-id list_id \ --user-id user_id components: schemas: RecipientPreferences: title: RecipientPreferences type: object properties: categories: $ref: '#/components/schemas/NotificationPreferences' nullable: true notifications: $ref: '#/components/schemas/NotificationPreferences' nullable: true NotificationPreferences: title: NotificationPreferences type: object additionalProperties: $ref: '#/components/schemas/NotificationPreferenceDetails' NotificationPreferenceDetails: title: NotificationPreferenceDetails type: object properties: status: $ref: '#/components/schemas/PreferenceStatus' rules: type: array items: $ref: '#/components/schemas/Rule' nullable: true channel_preferences: type: array items: $ref: '#/components/schemas/ChannelPreference' nullable: true required: - status PreferenceStatus: title: PreferenceStatus type: string enum: - OPTED_IN - OPTED_OUT - REQUIRED Rule: title: Rule type: object properties: start: type: string nullable: true until: type: string required: - until ChannelPreference: title: ChannelPreference type: object properties: channel: $ref: '#/components/schemas/ChannelClassification' required: - channel ChannelClassification: title: ChannelClassification type: string enum: - direct_message - email - push - sms - webhook - inbox securitySchemes: BearerAuth: type: http scheme: bearer ````