Skip to content

Tag Management

Tags enable granular subscription preferences for your subscribers. All tags are scoped to the organization associated with your API key.

Concept

graph TD
    subgraph "Organization"
        T1[Tag: product-updates]
        T2[Tag: weekly-digest]
        T3[Tag: marketing]
    end

    subgraph "Subscriber"
        S1[user@example.com]
    end

    S1 -->|subscribed| T1
    S1 -->|subscribed| T2
    S1 -.->|not subscribed| T3

Tag Limits by Tier

Tier Tag Limit
Free 3
Starter Unlimited
Professional Unlimited

Exceeding the tag limit on the Free tier returns a 403 Forbidden with error code limit_exceeded.

Creating a Tag

Bash
1
2
3
4
5
6
7
curl -X POST /api/v1/tags \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-updates",
    "display_name": "Product Updates"
  }'
Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
curl -X POST /api/v1/tags \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-updates",
    "display_name": "Product Updates",
    "description": "Receive updates about new features",
    "category": "newsletter",
    "sort_order": 10
  }'

The tag is automatically associated with the organization that owns the API key.

Tag Properties

Field Type Description
name string Technical name (slug), unique per organization
display_name string Display name in the preference center
description string Description for subscribers
category string Grouping (e.g., "newsletter", "notifications")
is_active boolean Whether the tag is shown in the preference center
sort_order integer Sort order

Organization Scope

Tag names must be unique within an organization, but different organizations can use the same tag names independently.

Listing Tags

All Tags

Bash
1
2
curl /api/v1/tags \
  -H "X-API-Key: $API_KEY"

Returns only tags belonging to your organization.

By Category

Bash
1
2
curl "/api/v1/tags?category=newsletter" \
  -H "X-API-Key: $API_KEY"

Active Tags Only

Bash
1
2
curl "/api/v1/tags?is_active=true" \
  -H "X-API-Key: $API_KEY"

Updating a Tag

Bash
1
2
3
4
5
6
7
curl -X PATCH /api/v1/tags/:id \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Product News",
    "description": "New features and improvements"
  }'

Deactivating a Tag

Deactivated tags are not shown in the preference center, but existing subscriptions are preserved.

Bash
1
2
3
curl -X PATCH /api/v1/tags/:id \
  -H "X-API-Key: $API_KEY" \
  -d '{"is_active": false}'

Deleting a Tag

Caution

Deleting a tag removes all subscriber associations.

Bash
1
2
curl -X DELETE /api/v1/tags/:id \
  -H "X-API-Key: $API_KEY"

Categories

Categories group tags in the preference center:

graph TD
    subgraph "Newsletter"
        T1[Product Updates]
        T2[Weekly Digest]
        T3[Company News]
    end

    subgraph "Notifications"
        T4[Security Alerts]
        T5[Usage Reports]
    end

    subgraph "Marketing"
        T6[Promotions]
        T7[Events]
    end

Category Overview

Bash
1
2
curl /api/v1/tags/categories \
  -H "X-API-Key: $API_KEY"

Response:

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "data": [
    {
      "name": "newsletter",
      "display_name": "Newsletter",
      "tag_count": 3
    },
    {
      "name": "notifications",
      "display_name": "Notifications",
      "tag_count": 2
    }
  ]
}

Subscribers per Tag

Subscriber Count

Bash
1
2
curl /api/v1/tags/:id/stats \
  -H "X-API-Key: $API_KEY"

Response:

JSON
1
2
3
4
5
6
{
  "tag_id": "uuid",
  "tag_name": "product-updates",
  "subscriber_count": 1523,
  "active_subscriber_count": 1450
}

Listing Subscribers

Bash
1
2
curl /api/v1/tags/:id/subscribers \
  -H "X-API-Key: $API_KEY"

Best Practices

Naming Conventions

Good Bad
product-updates Product Updates
weekly-digest weekly_digest
security-alerts securityAlerts

Hierarchy

Use categories for logical grouping:

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
categories:
  newsletter:
    - product-updates
    - weekly-digest
    - company-news
  notifications:
    - security-alerts
    - usage-reports
  marketing:
    - promotions
    - events

Default Tags

Define default tags for new subscribers:

Bash
1
2
3
4
5
6
curl -X POST /api/v1/subscribers \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "email": "user@example.com",
    "tags": ["essential-updates", "security-alerts"]
  }'

Tag Migration

When renaming a tag:

  1. Create a new tag
  2. Migrate subscribers
  3. Deactivate the old tag
  4. After a transition period: Delete the old tag
Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# 1. Create new tag
curl -X POST /api/v1/tags \
  -d '{"name": "product-news", "display_name": "Product News"}'

# 2. Migrate subscribers
curl -X POST /api/v1/subscribers/bulk-tag \
  -d '{
    "filter": {"tag": "product-updates"},
    "add_tags": ["product-news"],
    "remove_tags": ["product-updates"]
  }'

# 3. Deactivate old tag
curl -X PATCH /api/v1/tags/:old_id \
  -d '{"is_active": false}'

Monitor Tag Limits (Free Tier)

On the Free tier, you are limited to 3 tags. Check your current usage:

Bash
1
2
curl /api/v1/billing/usage \
  -H "X-API-Key: $API_KEY"