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

# Add Tags to Many Subscribers

> Add tags to up to 500 existing subscribers in one request

# Add Tags to Many Subscribers

Add one or more tags to up to 500 existing subscribers in a single request. This endpoint is built for reconciling historical or derived tags, so it behaves differently from the single-subscriber [Add Tag](/api-reference/subscribers/tags/add) endpoint in two important ways:

* **It never creates contacts.** Identifiers that do not match an existing subscriber come back in `notFound`, so a typo in a 3,000-row reconciliation cannot create 3,000 phantom contacts.
* **Tag automations are skipped by default.** Set `triggerAutomations` to `true` only when you actually want these contacts enrolled in `tag_added` sequences.

Identify subscribers by `emails`, `externalIds`, `subscriberIds`, or any combination. All identifier lists together must total at most 500 entries; split larger backlogs into batches.

## Request

<ParamField body="tags" type="string[]" required>
  Tag names to add to every matched subscriber, up to 25 per request. Names are
  normalized (lowercase, hyphens) the same way as everywhere else in Sequenzy.
</ParamField>

<ParamField body="emails" type="string[]">
  Subscriber emails to tag.
</ParamField>

<ParamField body="externalIds" type="string[]">
  Your app/customer/user IDs to tag.
</ParamField>

<ParamField body="subscriberIds" type="string[]">
  Sequenzy subscriber IDs to tag.
</ParamField>

<ParamField body="triggerAutomations" type="boolean">
  Whether `tag_added` sequences may enroll these contacts. Defaults to `false`.
  Requires the `automations:trigger` scope.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/bulk/tags/add" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["derived-churn-risk"],
    "emails": ["one@example.com", "two@example.com"]
  }'
```

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "tags": ["derived-churn-risk"],
    "requested": 3,
    "matched": 2,
    "updated": 2,
    "unchanged": 0,
    "failed": 0,
    "notFound": {
      "emails": ["ghost@example.com"],
      "externalIds": [],
      "subscriberIds": []
    },
    "failures": [],
    "triggeredAutomations": false,
    "message": "Tagged 2 subscribers (0 already in the target state, 0 failed)."
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "A maximum of 500 subscribers can be tagged per request. Split the request into smaller batches."
  }
  ```

  ```json 401 theme={null}
  {
    "success": false,
    "error": "Unauthorized"
  }
  ```

  ```json 403 theme={null}
  {
    "success": false,
    "error": "triggerAutomations requires the automations:trigger scope. Omit it to reconcile tags without enrolling contacts in sequences."
  }
  ```

  ```json 500 theme={null}
  {
    "success": false,
    "error": "Internal server error"
  }
  ```
</ResponseExample>

## Response Fields

| Field       | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `requested` | Identifiers you supplied                                        |
| `matched`   | Existing subscribers those identifiers resolved to              |
| `updated`   | Subscribers whose tags actually changed                         |
| `unchanged` | Subscribers that already carried every tag                      |
| `failed`    | Subscribers whose update failed; details in `failures` (max 50) |
| `notFound`  | Identifiers that did not resolve, grouped by kind. Not created. |

<Note>
  Use [Add Tag](/api-reference/subscribers/tags/add) or [Add Tags
  (Bulk)](/api-reference/subscribers/tags/add-bulk) when you want a single
  contact created on the fly. Use this endpoint when the contacts already exist
  and you are reconciling many of them at once.
</Note>