# Tags API



> The tags API gives integrations a lightweight way to manage subscriber labels. This guide explains when to use tags, when to use custom fields instead, how to list or create tags, and how to name tags so workspace users understand each label.



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

- Markdown page: https://mailrith.com/developers/tags.md

- Category: API Resources

- Reading time: 6 min read

- Last updated: 2026-07-13

- Related keywords: Tags API, Tags API developer docs, API Resources, API Resources developer docs, Mailrith developer docs, Mailrith public API, Manage Tags, Endpoint Overview, Create Tags Programmatically, Subscribers API, Segments API, API Reference



## AI Agent Notes

- Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document.

- Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise.

- Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using.



## What this guide covers

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



## Manage Tags

Tags are simple labels attached to subscribers. Use tags 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 label has a clear yes-or-no meaning, such as `Webinar 2026`, `Customer`, `Imported From CRM`, or `Needs Review`.

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

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

- 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 near-duplicate tags such as `webinar`, `Webinar`, and `Webinar Attendee` unless each tag has a different meaning.

## Endpoint Overview

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

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

Tags belong to the authenticated workspace. Never reuse a tag ID from one workspace with another workspace key.

Related OpenAPI operation groups:
- Tags

## Create Tags Programmatically

When you create a tag, use a human-readable name and a description that explains when users should apply the tag. A clear description helps future users understand why the tag exists.

When an outside system has already collected consent, your integration can create and apply Mailrith's GDPR consent tag names through the public API. Keep the original consent proof in the system that collected it.

Double opt-in is configured on forms and landing pages, not tags. Use tags only as labels for grouping, targeting, source tracking, and automation conditions.

**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"
  }'
```



## Related Guides

- [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the main way integrations write Subscriber data in `v1`. This guide explains when to list subscribers, when to upsert subscribers, 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 API supports saved segment definitions, imported subscriber rules, and previews for unsaved logic. This guide explains how segments behave, when to save segments, 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 the API reference to find exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.