> ## 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 (Bulk)

> Add multiple tags to a subscriber in one request

Add multiple tags to a subscriber in one request. Creates the subscriber and/or tags if they don't exist.

## Request Body

<ParamField body="email" type="string">
  Subscriber delivery email address. Required when creating a new subscriber.
</ParamField>

<ParamField body="externalId" type="string">
  Your app/customer/user ID for this subscriber. You can add tags with only
  `externalId` when the subscriber already exists.
</ParamField>

<ParamField body="tags" type="string[]" required>
  Array of tag names to add
</ParamField>

<ParamField body="customAttributes" type="object">
  Custom attributes to set on the subscriber.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "externalId": "user_123",
    "tags": ["customer", "newsletter", "pro-plan"]
  }'
```

## Auto-Creation Behavior

This endpoint automatically creates resources if they don't exist:

| Resource       | Behavior                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------- |
| **Subscriber** | Created if email doesn't exist - `active` status, or pending confirmation when double opt-in is enabled |
| **Tags**       | Each tag created and normalized if it doesn't exist                                                     |

## Double Opt-In

When the workspace has double opt-in enabled and this request creates a brand-new subscriber, the subscriber is stored pending confirmation and the confirmation email is queued. The tags are still applied immediately, but tag automations wait at their trigger step until the subscriber confirms. The response then includes an `optIn` object.

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "subscriber": {
      "id": "sub_abc123",
      "email": "user@example.com",
      "externalId": "user_123",
      "tags": ["customer", "newsletter", "pro-plan"],
      "created": false
    },
    "tags": {
      "added": ["customer", "newsletter", "pro-plan"],
      "created": ["pro-plan"]
    }
  }
  ```

  ```json 200 (new subscriber, double opt-in enabled) theme={null}
  {
    "success": true,
    "subscriber": {
      "id": "sub_abc123",
      "email": "user@example.com",
      "externalId": null,
      "tags": ["customer", "newsletter"],
      "created": true
    },
    "tags": {
      "added": ["customer", "newsletter"],
      "created": []
    },
    "optIn": {
      "required": true,
      "emailQueued": true
    }
  }
  ```

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

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

## Response Fields

| Field                | Description                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `subscriber.created` | `true` if subscriber was created by this request                                           |
| `tags.added`         | All tags now on the subscriber from this request                                           |
| `tags.created`       | Tags that were newly created (didn't exist before)                                         |
| `optIn`              | Present when the new subscriber requires double opt-in confirmation before becoming active |

## Use Cases

### New Customer Onboarding

```bash theme={null}
# Tag with multiple attributes at once
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new-customer@example.com",
    "tags": ["customer", "onboarding", "2024-cohort", "source-organic"],
    "customAttributes": {
      "plan": "pro",
      "signupDate": "2024-01-15"
    }
  }'
```

### Update Segments

```bash theme={null}
# Batch update subscriber segments
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "tags": ["enterprise", "high-value", "priority-support"]
  }'
```

<Note>
  Tags are normalized (lowercase, hyphens) before being added. The
  `tags.created` array shows which tag definitions were newly created by this
  request.
</Note>