> ## 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 to one or more lists > Subscribes a user to one or more lists, creating any list that does not yet exist. Optional preferences apply to each subscription. ## OpenAPI ````yaml /openapi-specs/openapi.documented.yml post /profiles/{user_id}/lists 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: Inbox description: Manage the messages in a user's in-app inbox. - 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: /profiles/{user_id}/lists: post: tags: - User Profiles summary: Subscribe to one or more lists description: >- Subscribes a user to one or more lists, creating any list that does not yet exist. Optional preferences apply to each subscription. operationId: profiles_subscribeToList parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IdempotencyExpiration' - name: user_id in: path description: >- A unique identifier representing the user associated with the requested user profile. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscribeToListsRequest' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SubscribeToListsResponse' examples: Example: value: status: SUCCESS '400': description: '' content: application/json: schema: $ref: '#/components/schemas/BadRequest' examples: Example: value: message: Example message text type: invalid_request_error 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 }); const response = await client.profiles.lists.subscribe('user_id', { lists: [{ listId: 'listId' }], }); console.log(response.status); - 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 ) response = client.profiles.lists.subscribe( user_id="user_id", lists=[{ "list_id": "listId" }], ) print(response.status) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/trycourier/courier-go\"\n\t\"github.com/trycourier/courier-go/option\"\n)\n\nfunc main() {\n\tclient := courier.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Profiles.Lists.Subscribe(\n\t\tcontext.TODO(),\n\t\t\"user_id\",\n\t\tcourier.ProfileListSubscribeParams{\n\t\t\tLists: []courier.SubscribeToListsRequestItemParam{{\n\t\t\t\tListID: \"listId\",\n\t\t\t}},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.Status)\n}\n" - lang: Java source: |- package com.courier.example; import com.courier.client.CourierClient; import com.courier.client.okhttp.CourierOkHttpClient; import com.courier.models.profiles.SubscribeToListsRequestItem; import com.courier.models.profiles.lists.ListSubscribeParams; import com.courier.models.profiles.lists.ListSubscribeResponse; public final class Main { private Main() {} public static void main(String[] args) { CourierClient client = CourierOkHttpClient.fromEnv(); ListSubscribeParams params = ListSubscribeParams.builder() .userId("user_id") .addList(SubscribeToListsRequestItem.builder() .listId("listId") .build()) .build(); ListSubscribeResponse response = client.profiles().lists().subscribe(params); } } - lang: Ruby source: >- require "courier" courier = Courier::Client.new(api_key: "My API Key") response = courier.profiles.lists.subscribe("user_id", lists: [{listId: "listId"}]) puts(response) - lang: PHP source: >- profiles->lists->subscribe( 'user_id', lists: [ [ 'listID' => 'listId', 'preferences' => [ 'categories' => [ 'foo' => [ 'status' => PreferenceStatus::OPTED_IN, 'channelPreferences' => [ ['channel' => ChannelClassification::DIRECT_MESSAGE] ], 'rules' => [['until' => 'until', 'start' => 'start']], ], ], 'notifications' => [ 'foo' => [ 'status' => PreferenceStatus::OPTED_IN, 'channelPreferences' => [ ['channel' => ChannelClassification::DIRECT_MESSAGE] ], 'rules' => [['until' => 'until', 'start' => 'start']], ], ], ], ], ], idempotencyKey: 'order-ORD-456-user-123', xIdempotencyExpiration: '1785312000', ); var_dump($response); } catch (APIException $e) { echo $e->getMessage(); } - lang: C# source: |- using System; using System.Collections.Generic; using TryCourier; using TryCourier.Models; using TryCourier.Models.Profiles.Lists; CourierClient client = new(); ListSubscribeParams parameters = new() { UserID = "user_id", Lists = [ new() { ListID = "listId", Preferences = new() { Categories = new Dictionary( ) { { "foo", new() { Status = PreferenceStatus.OptedIn, ChannelPreferences = [ new(ChannelClassification.DirectMessage) ], Rules = [ new() { Until = "until", Start = "start", }, ], } }, }, Notifications = new Dictionary( ) { { "foo", new() { Status = PreferenceStatus.OptedIn, ChannelPreferences = [ new(ChannelClassification.DirectMessage) ], Rules = [ new() { Until = "until", Start = "start", }, ], } }, }, }, }, ], }; var response = await client.Profiles.Lists.Subscribe(parameters); Console.WriteLine(response); - lang: CLI source: |- courier profiles:lists subscribe \ --api-key 'My API Key' \ --user-id user_id \ --list '{listId: listId}' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- A unique key that makes this request idempotent. If Courier receives another request with the same `Idempotency-Key`, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry `POST` requests after network failures without risking duplicate sends. The key is scoped to this endpoint. schema: type: string example: order-ORD-456-user-123 IdempotencyExpiration: name: x-idempotency-expiration in: header required: false description: >- How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year. schema: type: string example: '1785312000' schemas: SubscribeToListsRequest: title: SubscribeToListsRequest type: object properties: lists: type: array items: $ref: '#/components/schemas/SubscribeToListsRequestItem' required: - lists SubscribeToListsResponse: title: SubscribeToListsResponse type: object properties: status: type: string enum: - SUCCESS required: - status BadRequest: title: BadRequest type: object properties: type: type: string enum: - invalid_request_error required: - type allOf: - $ref: '#/components/schemas/BaseError' SubscribeToListsRequestItem: title: SubscribeToListsRequestItem type: object properties: listId: type: string preferences: $ref: '#/components/schemas/RecipientPreferences' nullable: true required: - listId BaseError: title: BaseError type: object properties: message: type: string description: A message describing the error that occurred. required: - message 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 ````