# Tags API



> The tags surface gives integrations a lightweight way to manage subscriber labels. This guide explains when tags are the right choice, when custom fields are better, how to list or create tags, and how to name tags so real workspace users understand them.



- Human page: https://mailrith.com/developers/tags

- Category: API Resources

- Reading time: 6 min read



## What this guide covers

Use tags as clear subscriber labels for targeting, forms, imports, and automation conditions.



## Manage Tags

Tags are simple labels attached to subscribers. They are useful for subscriber grouping, form source tracking, campaign targeting, automation conditions, import labels, and operational notes that do not need a typed custom field.

Use tags when the value is a label with a clear yes-or-no meaning, such as `Webinar 2026`, `Customer`, `Imported From CRM`, or `Needs Review`.

Use a custom field instead when the value is typed data that can vary per subscriber, such as plan, company size, birthday, signup date, or account owner.

1. List existing tags before creating new ones so your integration can reuse the workspace's current naming.
2. Create missing tags with clear names and descriptions.
3. Store the Mailrith tag IDs in your source-system mapping if you will reuse them.
4. Use tag IDs on subscriber upserts when you already know the mapping.
5. Use `new_tags` only when the source system intentionally owns the new label names.
6. Review the resulting tags in [Tags](https://mailrith.com/docs/tags.md) so workspace users see names they understand.

- Create tags programmatically when another system owns a source label.
- List tags before a migration so you can map old labels to existing Mailrith tags.
- Keep tag names understandable to real users because tags appear in Mailrith targeting and subscriber workflows.
- Avoid creating many near-duplicate tags such as `webinar`, `Webinar`, and `Webinar Attendee` unless they truly mean different things.

## Endpoint Overview

`GET /v1/tags` returns the workspace tag catalog in pages. Use it before importing or syncing subscribers so your integration can reuse existing tags.

`POST /v1/tags` creates a tag. Create tags before a bulk migration if you want clean mapping and predictable names, or let subscriber upsert requests create new tags when that is more convenient.

Tags belong to the authenticated workspace. A tag ID from one workspace should never be reused with another workspace key.

Related OpenAPI operation groups:
- Tags

## Create Tags Programmatically

When creating a tag, use a human-readable name and a description that explains when to apply the tag. A good description prevents future users from guessing why a tag exists.

Set `double_opt_in_enabled` to match the consent workflow you want for subscribers associated with that tag. If you are not sure which consent behavior applies, check the workspace's subscriber policy before automating tag creation.

**Create a Tag**

```bash
curl -X POST https://api.mailrith.com/v1/tags \
  -H "Authorization: Bearer mrk_example_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Webinar 2026",
    "description": "Applied to everyone who registered for the April webinar",
    "double_opt_in_enabled": false
  }'
```



## Related Guides

- [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the core subscriber write surface in `v1`. This guide explains when to list, when to upsert, how Mailrith chooses the workspace, what to include in an upsert body, and when to use async imports instead of many single requests.

- [Segments API](https://mailrith.com/developers/segments.md): The segments surface supports saved subscriber definitions, imported subscriber rules, and previews for unsaved logic. This guide explains how segments behave, when to save them, and why preview is the safest step before using complex subscriber rules.

- [API Reference](https://mailrith.com/developers/api-reference.md): The full API reference is generated from the same public contract used by the API worker and SDK tooling. Use it for exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.