`https://lumail.io/api/v1/subscribers/{subscriber}/tags`

Add one or more tags to an existing subscriber. Tags that don't exist will be created automatically. If the subscriber already has a tag, it will be skipped (no duplicate tags).

## Response

- **Success (200 OK)** - Returns the list of tags that were processed.
- **Error (404 Not Found)** - Subscriber not found.
- **Error (400 Bad Request)** - Invalid request body or empty tags array.

## Response Fields

| Field         | Type    | Description                                                         |
| ------------- | ------- | ------------------------------------------------------------------- |
| `success`     | boolean | Indicates if the operation was successful                           |
| `added`       | number  | Number of new tags added (excludes tags the subscriber already had) |
| `tags`        | array   | List of all tags that were processed                                |
| `tags[].id`   | string  | Unique identifier for the tag                                       |
| `tags[].name` | string  | Name of the tag                                                     |

## Request Schema

| Field  | Type     | Default  | Description                                                                |
| ------ | -------- | -------- | -------------------------------------------------------------------------- |
| `tags` | string[] | required | Array of tag names to add to the subscriber. At least one tag is required. |

## Path Parameters

| Parameter    | Type   | Description                                                                                       |
| ------------ | ------ | ------------------------------------------------------------------------------------------------- |
| `subscriber` | string | Subscriber identifier - can be either the subscriber ID (e.g., `sub_TTYPR5tWDh`) or email address |

## Usage Example

Use this API endpoint to:

- Add tags to subscribers for segmentation and targeting
- Automatically tag subscribers based on external events (purchases, signups, etc.)
- Sync tags from your CRM or other systems
- Trigger workflows based on tag additions

## Related Documentation

- [Get All Tags](/docs/api-reference/api-tags-get) - List available tags
- [Create Tags](/docs/api-reference/api-tags-post) - Create new tags
- [Remove Tags from Subscriber](/docs/api-reference/api-subscriber-tags-delete) - Remove tags from subscribers
- [Workflows](/docs/workflows) - Trigger workflows when tags are added
- [Action Step](/docs/workflows/workflow-action-step) - Add tags within workflows
- [Subscriber Events](/docs/features/subscriber-events) - View tag change history


## API Reference
**Method:** POST
**Endpoint:** /api/v1/subscribers/{subscriber}/tags

### SDK
```ts
import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: "YOUR_API_TOKEN" });

const { added, tags } = await lumail.subscribers.addTags(
  "subscriber@example.com",
  ["newsletter", "premium"]
);
console.log(`Added ${added} tags:`, tags);
```

### cURL
```bash
curl -X POST https://lumail.io/api/v1/subscribers/subscriber@example.com/tags \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["newsletter", "premium"]}'
```

### JavaScript
```javascript
const response = await fetch('https://lumail.io/api/v1/subscribers/subscriber@example.com/tags', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tags: ['newsletter', 'premium']
  }),
});

const data = await response.json();
console.log(data);
```

### Python
```python
import requests

url = "https://lumail.io/api/v1/subscribers/subscriber@example.com/tags"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "tags": ["newsletter", "premium"]
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)
```

### Success Response
```json
{
  "success": true,
  "added": 2,
  "tags": [
    {
      "id": "tag_JqaddtEx7z",
      "name": "newsletter"
    },
    {
      "id": "tag_rdEPhyjnfA",
      "name": "premium"
    }
  ]
}
```

### Error Response
```json
{
  "message": "Subscriber not found"
}
```