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

> Add a tag to a subscriber

Add a single tag to a subscriber. Creates the subscriber and/or tag 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 tag with only
  `externalId` when the subscriber already exists.
</ParamField>

<ParamField body="tag" type="string" required>
  Tag name to add. Will be normalized (lowercase, hyphens).
</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" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "externalId": "user_123",
    "tag": "customer"
  }'
```

## 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 |
| **Tag**        | Created and normalized if tag name doesn't exist                                                        |

This makes integration seamless—you don't need to pre-create anything.

## 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 tag is still applied immediately, but tag automations wait at their trigger step until the subscriber confirms. The response then includes an `optIn` object.

## Tag Normalization

Tags are automatically normalized when added:

```
"Pro Customer" → "pro-customer"
"VIP_User"     → "vip-user"
"Newsletter!"  → "newsletter"
```

## Responses

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

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

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

  ```json 409 theme={null}
  {
    "success": false,
    "error": "Subscriber identity conflict: email and externalId point to different subscribers."
  }
  ```

  ```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                                           |
| `tag.created`        | `true` if tag definition was created by this request                                       |
| `optIn`              | Present when the new subscriber requires double opt-in confirmation before becoming active |

## Use Cases

### Track Customer Status

```bash theme={null}
# When user purchases
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "buyer@example.com",
    "tag": "customer",
    "customAttributes": {
      "purchaseDate": "2024-01-15",
      "plan": "pro"
    }
  }'
```

### Segment by Interest

```bash theme={null}
# When user shows interest in a topic
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "reader@example.com",
    "tag": "interested-ai"
  }'
```

<Note>
  Adding a tag can trigger automations. If you have a sequence set to start when
  the tag is added, it will begin automatically.
</Note>