> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Subscription Topics

> Retrieve the ID and title of every live email subscription type, so your systems can reference them when setting unsubscribe preferences.

## **Overview**

This endpoint returns your live email subscription types with their IDs. Use it to look up the `topic_id` values you pass to [Set Subscription Preferences](./set-preferences).

## When to Use

Use this endpoint when:

* Building an integration that unsubscribes people from a specific subscription type
* Mapping your CRM's own list names onto Userpilot subscription types
* Confirming an ID before a bulk write

You can also read a single ID straight from the dashboard. On [**Settings > Email > Subscriptions**](https://run.userpilot.io/settings/email-settings/email-subscriptions), open the action menu on a row and select **Copy topic ID**.

## Prerequisites

* At least one email subscription type, created in [Settings > Email > Subscriptions](https://run.userpilot.io/settings/email-settings/email-subscriptions)
* Userpilot API Key from [Settings > Environment](https://run.userpilot.io/environment)

## Endpoint

```http theme={null}
[GET] https://analytex.userpilot.io/v1/email_subscription_topics
```

<Note>
  The endpoint URL uses the `analytex` environment. For EU data residency, use
  `analytex-eu` instead. See [Environment
  Settings](https://run.userpilot.io/environment) for your specific endpoint.
</Note>

{" "}

## Headers

| Header          | Value                  | Required |
| --------------- | ---------------------- | -------- |
| `Authorization` | `Token {YOUR_API_KEY}` | Yes      |
| `X-API-Version` | `2020-09-22`           | No       |

These endpoints have no versioned behavior, so `X-API-Version` is accepted and ignored. Send it if you already send it everywhere else.

## Example cURL Command

```bash theme={null}
curl -X GET https://analytex.userpilot.io/v1/email_subscription_topics \
  -H 'Authorization: Token {YOUR_API_KEY}' \
  -H 'X-API-Version: 2020-09-22'
```

## Response

```json theme={null}
{
  "topics": [
    { "id": 3, "title": "Promotions and Marketing" },
    { "id": 7, "title": "Product Newsletter" }
  ]
}
```

<Note>
  Only live subscription types appear here. A subscription type still in draft has an ID and accepts writes, but you need to copy that ID from the dashboard.
</Note>

Two things are deliberately absent from this list:

* **Unsubscribed from all** is a scope rather than a subscription type. Set it with `"all": true` instead of a `topic_id`.
* Titles are never accepted as input anywhere in the API. Renaming a subscription type would quietly break your integration, so IDs are the only reference.

## Common Issues

| Error                         | Cause                                    | Solution                                                          |
| ----------------------------- | ---------------------------------------- | ----------------------------------------------------------------- |
| 401 Unauthorized              | Invalid or suspended API key             | Verify your key in Environment settings                           |
| Empty `topics` array          | No live subscription types               | Create one, or link an existing draft to an email so it goes live |
| An ID you expected is missing | That subscription type is still in draft | Copy the ID from the dashboard row menu                           |

## Related

* [Set Subscription Preferences](./set-preferences) - Unsubscribe or re-subscribe addresses
* [Manage unsubscribes](/in-app-engagement/emails/manage-unsubscribes) - The same job from the dashboard
* [Webhooks](/integrations/webhooks) - Receive an event when someone unsubscribes in Userpilot