Subscribers

Subscribers are the core entity in SubscribeFlow. Each subscriber has an email address, a status, optional metadata, and zero or more tags.

Create a subscriber

PythonTypeScriptcURL

subscriber = await client.subscribers.create(
    email="alice@example.com",
    tags=["newsletter", "product-updates"],
    metadata={"source": "website", "plan": "starter"},
)
print(f"Created: {subscriber.id}")

const subscriber = await client.subscribers.create({
  email: 'alice@example.com',
  tags: ['newsletter', 'product-updates'],
  metadata: { source: 'website', plan: 'starter' },
});

console.log('Created:', subscriber.id);

curl -X POST https://api.subscribeflow.net/api/v1/subscribers \
  -H "X-API-Key: sf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "tags": ["newsletter", "product-updates"],
    "metadata": {"source": "website", "plan": "starter"}
  }'

Info

If you pass tag names that do not exist yet, SubscribeFlow creates them automatically.

Get a subscriber

Retrieve a subscriber by ID or by email address.

PythonTypeScriptcURL

# By ID
subscriber = await client.subscribers.get("subscriber-id")

# By email
subscriber = await client.subscribers.get_by_email("alice@example.com")

// By ID
const subscriber = await client.subscribers.get('subscriber-id');

// By email
const subscriber = await client.subscribers.getByEmail('alice@example.com');

# By ID
curl https://api.subscribeflow.net/api/v1/subscribers/SUBSCRIBER_ID \
  -H "X-API-Key: sf_live_..."

# By email
curl "https://api.subscribeflow.net/api/v1/subscribers/by-email?email=alice@example.com" \
  -H "X-API-Key: sf_live_..."

List subscribers with pagination

SubscribeFlow uses cursor-based pagination. Every list response includes a next_cursor value. Pass it to the next request to fetch the following page.

PythonTypeScriptcURL

result = await client.subscribers.list(limit=50, status="active")
for subscriber in result:
    print(subscriber.email)

# Fetch the next page
while result.next_cursor:
    result = await client.subscribers.list(
        cursor=result.next_cursor, limit=50,
    )
    for subscriber in result:
        print(subscriber.email)

let { items, cursor } = await client.subscribers.list({
  limit: 50,
  status: 'active',
});

for (const subscriber of items) {
  console.log(subscriber.email);
}

// Fetch the next page
while (cursor) {
  const result = await client.subscribers.list({ cursor, limit: 50 });
  items = result.items;
  cursor = result.cursor;
  for (const subscriber of items) {
    console.log(subscriber.email);
  }
}

# First page
curl "https://api.subscribeflow.net/api/v1/subscribers?limit=50&status=active" \
  -H "X-API-Key: sf_live_..."

# Next page (use the cursor value from the previous response)
curl "https://api.subscribeflow.net/api/v1/subscribers?limit=50&cursor=CURSOR_VALUE" \
  -H "X-API-Key: sf_live_..."

Update a subscriber

You can update the email address, status, or metadata of an existing subscriber.

PythonTypeScriptcURL

updated = await client.subscribers.update(
    "subscriber-id",
    metadata={"plan": "professional"},
)

const updated = await client.subscribers.update('subscriber-id', {
  metadata: { plan: 'professional' },
});

curl -X PATCH https://api.subscribeflow.net/api/v1/subscribers/SUBSCRIBER_ID \
  -H "X-API-Key: sf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"plan": "professional"}}'

Delete a subscriber

Deleting a subscriber removes all associated data permanently. This is the recommended way to fulfil DSGVO/DSG deletion requests.

PythonTypeScriptcURL

await client.subscribers.delete("subscriber-id")

await client.subscribers.delete('subscriber-id');

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

Warning

Deletion is irreversible. All subscriber data, tag associations, and event history are permanently removed.

Manage tags

Add or remove tags from an existing subscriber without replacing the full tag list.

Add tags

PythonTypeScriptcURL

await client.subscribers.add_tags(
    "subscriber-id",
    tags=["webinar-attendees", "beta-testers"],
)

await client.subscribers.addTags('subscriber-id', {
  tags: ['webinar-attendees', 'beta-testers'],
});

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": ["webinar-attendees", "beta-testers"]}'

Remove a tag

PythonTypeScriptcURL

await client.subscribers.remove_tag("subscriber-id", "beta-testers")

await client.subscribers.removeTag('subscriber-id', 'beta-testers');

curl -X DELETE \
  "https://api.subscribeflow.net/api/v1/subscribers/SUBSCRIBER_ID/tags/beta-testers" \
  -H "X-API-Key: sf_live_..."

Hands-On: Import your first 100 subscribers

Use a loop to batch-create subscribers from a CSV or list. The example below reads a simple list and creates each subscriber with an imported tag.

PythonTypeScriptcURL

import asyncio
from subscribeflow import SubscribeFlowClient

emails = [
    "alice@example.com",
    "bob@example.com",
    # ... up to 100 emails
]

async def main():
    async with SubscribeFlowClient(api_key="sf_live_...") as client:
        for email in emails:
            subscriber = await client.subscribers.create(
                email=email,
                tags=["imported"],
                metadata={"source": "csv-import"},
            )
            print(f"Imported: {subscriber.email}")

asyncio.run(main())

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

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

const emails = [
  'alice@example.com',
  'bob@example.com',
  // ... up to 100 emails
];

for (const email of emails) {
  const subscriber = await client.subscribers.create({
    email,
    tags: ['imported'],
    metadata: { source: 'csv-import' },
  });
  console.log('Imported:', subscriber.email);
}

# Loop through a list of emails
for EMAIL in alice@example.com bob@example.com; do
  curl -X POST https://api.subscribeflow.net/api/v1/subscribers \
    -H "X-API-Key: sf_live_..." \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$EMAIL\", \"tags\": [\"imported\"], \"metadata\": {\"source\": \"csv-import\"}}"
  echo
done