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.

6 min read

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.

List existing tags before you create new tags so your integration can reuse the workspace's current tag names.
Create missing tags with clear names and descriptions.
Store the Mailrith tag IDs in your source-system mapping if your integration will reuse the tags.
Use tag IDs on subscriber upserts when your integration already knows the mapping.
Use new_tags only when the source system intentionally owns the new label names.
Review the created or reused tags in Tags. 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.

GET /v1/tags

List tags

Returns tags in the authenticated workspace.

View Schema

POST /v1/tags

Create a tag

Creates a new tag in the authenticated workspace. The GDPR consent tag names can be created and applied like other tags when you need to apply consent collected outside Mailrith. Tag-level double opt-in fields are no longer accepted; configure double opt-in on forms and landing pages instead.

View Schema

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

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

Need Help Shipping an Integration?

Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.

Contact Mailrith

Subscribers API

Custom Fields API