> ## 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.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Get user's Preferences

> Returns a user's preference overrides with paging, one entry per subscription topic they have set a choice for.



## OpenAPI

````yaml /openapi-specs/openapi.documented.yml get /users/{user_id}/preferences
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: Previews
    description: >-
      Render a template's email content on real email clients and read back the
      screenshots, so you can check how it looks before you send it.
  - 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:
  /users/{user_id}/preferences:
    get:
      tags:
        - User Preferences
      summary: Get user's Preferences
      description: >-
        Returns a user's preference overrides with paging, one entry per
        subscription topic they have set a choice for.
      operationId: users_preferences_list
      parameters:
        - name: user_id
          in: path
          description: >-
            A unique identifier associated with the user whose preferences you
            wish to retrieve.
          required: true
          schema:
            type: string
        - name: tenant_id
          in: query
          description: Query the preferences of a user for this specific tenant context.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersUserPreferencesListResponse'
              examples:
                Example:
                  value:
                    paging:
                      cursor: MTpFWUNFRkRRN0c1WERTRTU2
                      more: true
                    items:
                      - custom_routing:
                          - direct_message
                        default_status: OPTED_IN
                        has_custom_routing: true
                        section_id: ps_01kx4h2jdafq8bk99mj9q2gsa3
                        section_name: string
                        status: OPTED_IN
                        topic_id: pt_01kx4h2jdafq8bk99mj9q2gsa2
                        topic_name: string
        '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 preference = await
            client.users.preferences.retrieve('user_id');


            console.log(preference.items);
        - 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
            )
            preference = client.users.preferences.retrieve(
                user_id="user_id",
            )
            print(preference.items)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/trycourier/courier-go/v4\"\n\t\"github.com/trycourier/courier-go/v4/option\"\n)\n\nfunc main() {\n\tclient := courier.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tpreference, err := client.Users.Preferences.Get(\n\t\tcontext.TODO(),\n\t\t\"user_id\",\n\t\tcourier.UserPreferenceGetParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", preference.Items)\n}\n"
        - lang: Java
          source: >-
            package com.courier.example;


            import com.courier.client.CourierClient;

            import com.courier.client.okhttp.CourierOkHttpClient;

            import
            com.courier.models.users.preferences.PreferenceRetrieveParams;

            import
            com.courier.models.users.preferences.PreferenceRetrieveResponse;


            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    CourierClient client = CourierOkHttpClient.fromEnv();

                    PreferenceRetrieveResponse preference = client.users().preferences().retrieve("user_id");
                }
            }
        - lang: Ruby
          source: |-
            require "courier"

            courier = Courier::Client.new(api_key: "My API Key")

            preference = courier.users.preferences.retrieve("user_id")

            puts(preference)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use Courier\Client;

            use Courier\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('COURIER_API_KEY') ?: 'My API
            Key');


            try {
              $preference = $client->users->preferences->retrieve(
                'user_id', tenantID: 'tenant_id'
              );

              var_dump($preference);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: C#
          source: >-
            using System;

            using TryCourier;

            using TryCourier.Models.Users.Preferences;


            CourierClient client = new();


            PreferenceRetrieveParams parameters = new() { UserID = "user_id" };


            var preference = await
            client.Users.Preferences.Retrieve(parameters);


            Console.WriteLine(preference);
        - lang: CLI
          source: |-
            courier users:preferences retrieve \
              --api-key 'My API Key' \
              --user-id user_id
components:
  schemas:
    UsersUserPreferencesListResponse:
      title: UsersUserPreferencesListResponse
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
          description: Deprecated - Paging not implemented on this endpoint
        items:
          type: array
          items:
            $ref: '#/components/schemas/UsersTopicPreference'
          description: The Preferences associated with the user_id.
      required:
        - paging
        - items
    BadRequest:
      title: BadRequest
      type: object
      properties:
        type:
          type: string
          enum:
            - invalid_request_error
      required:
        - type
      allOf:
        - $ref: '#/components/schemas/BaseError'
    Paging:
      title: Paging
      type: object
      properties:
        cursor:
          type: string
          nullable: true
        more:
          type: boolean
      required:
        - more
    UsersTopicPreference:
      title: UsersTopicPreference
      type: object
      properties:
        custom_routing:
          type: array
          items:
            $ref: '#/components/schemas/ChannelClassification'
          nullable: true
          description: >-
            The channels the user has chosen to receive this topic on, present
            only when has_custom_routing is true. One or more of:
            direct_message, email, push, sms, webhook, inbox.
        default_status:
          allOf:
            - $ref: '#/components/schemas/PreferenceStatus'
          description: >-
            The topic's default status, returned on reads. It applies whenever
            the user has no override of their own (status equals this value).
        has_custom_routing:
          type: boolean
          nullable: true
          description: >-
            Whether the user has chosen specific delivery channels for this
            topic (listed in custom_routing) rather than the topic's default
            routing.
        section_id:
          type: string
          description: >-
            The unique identifier of the section this topic belongs to. Always
            present when listing a user's preferences; omitted by the
            single-topic read when the topic has no resolvable section.
        section_name:
          type: string
          description: >-
            The display name of the section this topic belongs to. Always
            present when listing a user's preferences; omitted by the
            single-topic read when the topic has no resolvable section.
        status:
          allOf:
            - $ref: '#/components/schemas/PreferenceStatus'
          description: >-
            The user's subscription status for this topic. OPTED_IN or OPTED_OUT
            reflect the user's own choice; REQUIRED is a topic-level default set
            in the preferences editor, not a user choice.
        topic_id:
          type: string
          description: >-
            The unique identifier of the subscription topic this preference
            applies to.
        topic_name:
          type: string
          description: The display name of the subscription topic, returned on reads.
        digest_schedule_id:
          type: string
          description: >-
            The digest schedule this recipient is on for the topic. Omitted
            rather than null when they have not chosen one, in which case the
            topic's default schedule applies. Ids come from the topic's digest
            configuration, returned on any read of the topic.


            Also omitted when the schedule they chose has since been deleted or
            disabled: the recipient is on the topic's default from that point
            on, which is how a send already resolves it, so the field reports
            what would actually be used rather than a dead id.
      required:
        - default_status
        - status
        - topic_id
        - topic_name
    BaseError:
      title: BaseError
      type: object
      properties:
        message:
          type: string
          description: A message describing the error that occurred.
      required:
        - message
    ChannelClassification:
      title: ChannelClassification
      type: string
      enum:
        - direct_message
        - email
        - push
        - sms
        - webhook
        - inbox
    PreferenceStatus:
      title: PreferenceStatus
      type: string
      enum:
        - OPTED_IN
        - OPTED_OUT
        - REQUIRED
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````