Tags

Tags let you segment your subscriber base by interest, topic, or any category you define. Subscribers can hold multiple tags, and tags can be public (visible in the preference center) or private (internal use only).

Create a tag

PythonTypeScriptcURL

tag = await client.tags.create(
    name="Product Updates",
    description="New features and improvements",
    category="product",
    is_public=True,
)
print(f"Created: {tag.name} ({tag.slug})")

const tag = await client.tags.create({
  name: 'Product Updates',
  description: 'New features and improvements',
  category: 'product',
  is_public: true,
});

console.log('Created:', tag.name, `(${tag.slug})`);

curl -X POST https://api.subscribeflow.net/api/v1/tags \
  -H "X-API-Key: sf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Updates",
    "description": "New features and improvements",
    "category": "product",
    "is_public": true
  }'

Info

A URL-safe slug is generated automatically from the tag name. You can also provide a custom slug.

List and filter tags

Retrieve all tags or filter by category.

PythonTypeScriptcURL

# All tags
tags = await client.tags.list()
for tag in tags:
    print(f"{tag.name}: {tag.subscriber_count} subscribers")

# Filter by category
product_tags = await client.tags.list(category="product")

// All tags
const { items } = await client.tags.list();
for (const tag of items) {
  console.log(`${tag.name}: ${tag.subscriber_count} subscribers`);
}

// Filter by category
const productTags = await client.tags.list({ category: 'product' });

# All tags
curl https://api.subscribeflow.net/api/v1/tags \
  -H "X-API-Key: sf_live_..."

# Filter by category
curl "https://api.subscribeflow.net/api/v1/tags?category=product" \
  -H "X-API-Key: sf_live_..."

Get subscriber count

Each tag response includes a subscriber_count field. You can also retrieve a single tag to check its current count.

PythonTypeScriptcURL

tag = await client.tags.get("tag-id")
print(f"{tag.name} has {tag.subscriber_count} subscribers")

const tag = await client.tags.get('tag-id');
console.log(`${tag.name} has ${tag.subscriber_count} subscribers`);

curl https://api.subscribeflow.net/api/v1/tags/TAG_ID \
  -H "X-API-Key: sf_live_..."

Update a tag

PythonTypeScriptcURL

await client.tags.update(
    "tag-id",
    description="Weekly product updates and release notes",
    is_public=True,
)

await client.tags.update('tag-id', {
  description: 'Weekly product updates and release notes',
  is_public: true,
});

curl -X PATCH https://api.subscribeflow.net/api/v1/tags/TAG_ID \
  -H "X-API-Key: sf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"description": "Weekly product updates and release notes", "is_public": true}'

Archive a tag (soft delete)

Deleting a tag removes it from the system. Existing subscriber associations are removed, but the subscribers themselves remain.

PythonTypeScriptcURL

await client.tags.delete("tag-id")

await client.tags.delete('tag-id');

curl -X DELETE https://api.subscribeflow.net/api/v1/tags/TAG_ID \
  -H "X-API-Key: sf_live_..."

Warning

Deleting a tag unsubscribes all associated subscribers from that tag. This cannot be undone.

Hands-On: Segment your audience with tags

Create a set of topic tags and assign them to subscribers. This example sets up a basic interest-based segmentation.

PythonTypeScriptcURL

import asyncio
from subscribeflow import SubscribeFlowClient

async def main():
    async with SubscribeFlowClient(api_key="sf_live_...") as client:
        # Create topic tags
        for tag_name in ["Engineering Blog", "Product Updates", "Events"]:
            await client.tags.create(
                name=tag_name,
                category="content",
                is_public=True,
            )

        # Tag existing subscribers
        await client.subscribers.add_tags(
            "subscriber-id",
            tags=["engineering-blog", "events"],
        )
        print("Subscriber tagged successfully")

asyncio.run(main())

import { SubscribeFlowClient } from '@subscribeflow/sdk';

const client = new SubscribeFlowClient({
  apiKey: 'sf_live_...',
});

// Create topic tags
for (const name of ['Engineering Blog', 'Product Updates', 'Events']) {
  await client.tags.create({
    name,
    category: 'content',
    is_public: true,
  });
}

// Tag existing subscribers
await client.subscribers.addTags('subscriber-id', {
  tags: ['engineering-blog', 'events'],
});

console.log('Subscriber tagged successfully');

# Create tags
for TAG in "Engineering Blog" "Product Updates" "Events"; do
  curl -X POST https://api.subscribeflow.net/api/v1/tags \
    -H "X-API-Key: sf_live_..." \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"$TAG\", \"category\": \"content\", \"is_public\": true}"
  echo
done

# Tag a subscriber
curl -X POST https://api.subscribeflow.net/api/v1/subscribers/SUBSCRIBER_ID/tags \
  -H "X-API-Key: sf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tags": ["engineering-blog", "events"]}'