---
title: "Bulk subscribe contacts to topics"
method: POST
path: "/audience/contacts/topics/bulk"
tags: ["Audience"]
---

# Bulk subscribe contacts to topics

`POST /audience/contacts/topics/bulk`

## Request

- Base URL: `https://app.lettr.com/api`
- URL: `https://app.lettr.com/api/audience/contacts/topics/bulk`
- Auth: HTTP bearer

Subscribe every combination of `contact_ids × topic_ids` (up to 1000 contacts × 50 topics). Pairs that already exist are reported in `already_subscribed`. Requires the `audience:write` scope and is blocked for sandbox API keys.

## Request body

- BulkAudienceContactTopicsRequest: Bulk subscribe/unsubscribe contacts to/from topics. All combinations of contact_ids × topic_ids are processed.
  - `contact_ids` string[], required
  - `topic_ids` string[], required

## Response `200`

OK

- BulkSubscribeContactsToTopicsResponse
  - `message` string, required
  - `data` object, required
    - `subscribed` integer, required: Newly subscribed pairs
    - `already_subscribed` integer, required: Pairs that already existed
    - `total_pairs` integer, required: Total contact × topic pairs processed

## Other responses

- `401`: Unauthorized - Missing or invalid API key
- `403`: Forbidden - API key does not have the required scope
- `422`: Validation error
- `500`: Internal server error
- `503`: Service unavailable - the API key could not be verified, so the request was not processed. This does not mean the key is invalid; retry after the delay given in the Retry-After header.

---

[API](https://skmtc.dev/lettr/apis/lettr-api.md) · [All operations](https://skmtc.dev/lettr/apis/lettr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lettr/apis/lettr-api/revisions/48ef0dac1ebd?raw)