Skip to content

API Reference

Comprehensive documentation of all Subscribe Flow API endpoints.

Interactive Documentation

Format URL Description
Swagger UI /docs Interactive API exploration with try-it-out
ReDoc /redoc Clear reference documentation
OpenAPI /openapi.json OpenAPI 3.1 Specification

Base URL

Environment URL
Production https://api.subscribeflow.net
Local http://localhost:8000

Authentication

Subscribe Flow supports dual authentication: API key OR session cookie. Every /api/v1/* endpoint accepts either method.

API Key (Programmatic Access)

All admin endpoints (/api/v1/*) accept API key authentication:

Bash
1
2
curl -X GET "http://localhost:8000/api/v1/subscribers" \
  -H "X-API-Key: sf_live_your_api_key"

API keys are organization-scoped. Each key belongs to exactly one organization.

Scopes:

Scope Description
subscribers:read Read subscribers
subscribers:write Create/update subscribers
subscribers:delete Delete subscribers
tags:read Read tags
tags:write Create/update/delete tags
webhooks:manage Manage webhook endpoints

Dashboard users authenticate via magic link, which sets an HTTP-only sf_session cookie. Organization context is provided via the X-Organization-Id header:

Bash
1
2
3
curl -X GET "http://localhost:8000/api/v1/subscribers" \
  -H "X-Organization-Id: 550e8400-e29b-41d4-a716-446655440000" \
  -b "sf_session=eyJhbGciOi..."

Token (Preference Center)

Preference Center endpoints use JWT tokens as query parameters:

Bash
1
curl "http://localhost:8000/preference-center?token=eyJhbGciOi..."

Auth API

Endpoints for magic link login, session management, and organization management. These endpoints do not require API key auth.

HTTP
1
POST /auth/magic-link

Request Body:

JSON
1
2
3
{
  "email": "user@example.com"
}

Response (200 OK):

JSON
1
2
3
{
  "message": "If the email exists, a magic link has been sent."
}

Anti-Enumeration

Always returns 200 regardless of whether the email exists.

Verifies the token and sets an HTTP-only session cookie (sf_session, 7 days).

HTTP
1
GET /auth/verify?token={magic_link_token}

Response (200 OK):

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "has_organizations": true,
  "organizations": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "My Company",
      "slug": "my-company",
      "role": "owner"
    }
  ]
}

Errors:

Status Error Description
401 magic_link_expired Token has expired
401 magic_link_already_used Token was already used
401 invalid_token Token not found or invalid

Create Organization

Requires session auth (cookie). The calling user becomes the owner.

HTTP
1
POST /auth/organizations

Request Body:

JSON
1
2
3
4
{
  "name": "My Company",
  "slug": "my-company"
}

Response (200 OK):

JSON
1
2
3
4
5
{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "name": "My Company",
  "slug": "my-company"
}

List Organizations

Requires session auth. Returns all organizations the current user belongs to.

HTTP
1
GET /auth/organizations

Response (200 OK):

JSON
1
2
3
4
5
6
7
8
[
  {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "name": "My Company",
    "slug": "my-company",
    "role": "owner"
  }
]

Logout

Clears the session cookie.

HTTP
1
POST /auth/logout

Response (200 OK):

JSON
1
2
3
{
  "message": "Logged out successfully."
}

Subscribers API

Create Subscriber

Creates a new subscriber with optional tag subscriptions.

HTTP
1
POST /api/v1/subscribers

Auth: API Key or Session

Request Body:

JSON
1
2
3
4
5
6
7
8
{
  "email": "user@example.com",
  "tags": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
  "metadata": {
    "source": "website",
    "campaign": "summer-2026"
  }
}

Response (201 Created):

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "status": "active",
  "tags": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Product Updates",
      "slug": "product-updates"
    }
  ],
  "metadata": {
    "source": "website",
    "campaign": "summer-2026"
  },
  "created_at": "2026-02-03T10:30:00Z",
  "updated_at": "2026-02-03T10:30:00Z"
}

Errors:

Status Error Description
400 validation_error Invalid email address
402 limit_exceeded Subscriber limit reached for current plan
409 conflict Email already exists

List Subscribers

Lists subscribers with pagination and filtering.

HTTP
1
GET /api/v1/subscribers

Auth: API Key or Session

Query Parameters:

Parameter Type Default Description
cursor string - Cursor for the next page
limit integer 50 Max. results (1-100)
status string - Filter: active, unsubscribed, bounced, complained
tag string - Filter by tag ID
sort string created_at Sort by: created_at, updated_at, email
order string desc Direction: asc, desc

Response (200 OK):

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "status": "active",
      "tags": [],
      "created_at": "2026-02-03T10:30:00Z",
      "updated_at": "2026-02-03T10:30:00Z"
    }
  ],
  "total": 1234,
  "next_cursor": "eyJpZCI6IjU1MGU4NDAwLi4uIn0="
}

Response Headers:

Header Description
X-Total-Count Total number of subscribers
Link Pagination links (RFC 5988)

Get Subscriber

HTTP
1
GET /api/v1/subscribers/{subscriber_id}

Auth: API Key or Session

Get Subscriber by Email

HTTP
1
GET /api/v1/subscribers/by-email/{email}

Auth: API Key or Session

Update Subscriber

HTTP
1
PUT /api/v1/subscribers/{subscriber_id}

Auth: API Key or Session

Request Body:

JSON
1
2
3
4
5
6
{
  "metadata": {
    "plan": "premium"
  },
  "status": "unsubscribed"
}

Response (200 OK): Updated subscriber

Delete Subscriber

Permanently deletes a subscriber.

HTTP
1
DELETE /api/v1/subscribers/{subscriber_id}

Auth: API Key or Session

Response: 204 No Content

Manage Subscriber Tags

Add Tags

HTTP
1
POST /api/v1/subscribers/{subscriber_id}/tags

Auth: API Key or Session

Request Body:

JSON
1
2
3
{
  "tag_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
}

Remove Tag

HTTP
1
DELETE /api/v1/subscribers/{subscriber_id}/tags/{tag_id}

Auth: API Key or Session

Get Subscriber Tags

HTTP
1
GET /api/v1/subscribers/{subscriber_id}/tags

Auth: API Key or Session

Tags API

Create Tag

HTTP
1
POST /api/v1/tags

Auth: API Key or Session

Request Body:

JSON
1
2
3
4
5
6
7
8
{
  "name": "Product Updates",
  "slug": "product-updates",
  "description": "Receive notifications about new features",
  "metadata": {
    "category": "product"
  }
}

Response (201 Created):

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Product Updates",
  "slug": "product-updates",
  "description": "Receive notifications about new features",
  "metadata": {
    "category": "product"
  },
  "subscriber_count": 0,
  "created_at": "2026-02-03T10:30:00Z",
  "updated_at": "2026-02-03T10:30:00Z"
}

List Tags

HTTP
1
GET /api/v1/tags

Auth: API Key or Session

Query Parameters:

Parameter Type Default Description
cursor string - Cursor for the next page
limit integer 50 Max. results (1-100)
sort string name Sort by: name, created_at, subscriber_count
order string asc Direction: asc, desc

Get Tag

HTTP
1
GET /api/v1/tags/{tag_id}

Auth: API Key or Session

Get Tag by Name

HTTP
1
GET /api/v1/tags/by-name/{name}

Auth: API Key or Session

Update Tag

HTTP
1
PUT /api/v1/tags/{tag_id}

Auth: API Key or Session

Request Body:

JSON
1
2
3
4
{
  "name": "New Name",
  "description": "New description"
}

Delete Tag

HTTP
1
DELETE /api/v1/tags/{tag_id}

Auth: API Key or Session

Response: 204 No Content

Impact on Subscribers

Deleting a tag automatically removes all subscriber associations.

Templates API

Create Template

HTTP
1
POST /api/v1/templates

Auth: API Key or Session

List Templates

HTTP
1
GET /api/v1/templates

Auth: API Key or Session

Get Template

HTTP
1
GET /api/v1/templates/{template_id}

Auth: API Key or Session

Update Template

HTTP
1
PUT /api/v1/templates/{template_id}

Auth: API Key or Session

Delete Template

HTTP
1
DELETE /api/v1/templates/{template_id}

Auth: API Key or Session

Preview Template

HTTP
1
POST /api/v1/templates/{template_id}/preview

Auth: API Key or Session

Emails API

Send Email

HTTP
1
POST /api/v1/emails/send

Auth: API Key or Session

Errors:

Status Error Description
402 limit_exceeded Monthly email limit reached for current plan

Campaigns API

Create Campaign

HTTP
1
POST /api/v1/campaigns

Auth: API Key or Session

List Campaigns

HTTP
1
GET /api/v1/campaigns

Auth: API Key or Session

Get Campaign

HTTP
1
GET /api/v1/campaigns/{campaign_id}

Auth: API Key or Session

Update Campaign

HTTP
1
PUT /api/v1/campaigns/{campaign_id}

Auth: API Key or Session

Send Campaign

HTTP
1
POST /api/v1/campaigns/{campaign_id}/send

Auth: API Key or Session

Cancel Campaign

HTTP
1
POST /api/v1/campaigns/{campaign_id}/cancel

Auth: API Key or Session

Retry Campaign

HTTP
1
POST /api/v1/campaigns/{campaign_id}/retry

Auth: API Key or Session

Duplicate Campaign

HTTP
1
POST /api/v1/campaigns/{campaign_id}/duplicate

Auth: API Key or Session

Count Campaign Recipients

HTTP
1
POST /api/v1/campaigns/{campaign_id}/count-recipients

Auth: API Key or Session

Email Triggers API

Create Trigger

HTTP
1
POST /api/v1/email-triggers

Auth: API Key or Session

List Triggers

HTTP
1
GET /api/v1/email-triggers

Auth: API Key or Session

Get Trigger

HTTP
1
GET /api/v1/email-triggers/{trigger_id}

Auth: API Key or Session

Update Trigger

HTTP
1
PUT /api/v1/email-triggers/{trigger_id}

Auth: API Key or Session

Delete Trigger

HTTP
1
DELETE /api/v1/email-triggers/{trigger_id}

Auth: API Key or Session

Outgoing Webhooks API

Create Webhook Endpoint

HTTP
1
POST /api/v1/webhooks

Auth: API Key or Session

Request Body:

JSON
1
2
3
4
5
6
7
8
9
{
  "url": "https://your-app.com/webhooks/subscribeflow",
  "events": [
    "subscriber.created",
    "subscriber.updated",
    "tag.subscribed"
  ],
  "description": "Main production webhook"
}

Response (201 Created):

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "id": "8fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://your-app.com/webhooks/subscribeflow",
  "events": ["subscriber.created", "subscriber.updated", "tag.subscribed"],
  "description": "Main production webhook",
  "status": "active",
  "signing_secret": "whsec_abc123...",
  "created_at": "2026-02-03T10:30:00Z",
  "updated_at": "2026-02-03T10:30:00Z"
}

Signing Secret

The signing_secret is only returned upon creation. Store it securely for signature verification.

Available Events:

Event Description
subscriber.created New subscriber created
subscriber.updated Subscriber updated
subscriber.deleted Subscriber deleted
tag.subscribed Tag subscribed
tag.unsubscribed Tag unsubscribed
subscriber.note_added Note added to subscriber

List Webhooks

HTTP
1
GET /api/v1/webhooks

Auth: API Key or Session

Get Webhook

HTTP
1
GET /api/v1/webhooks/{webhook_id}

Auth: API Key or Session

Update Webhook

HTTP
1
PUT /api/v1/webhooks/{webhook_id}

Auth: API Key or Session

Delete Webhook

HTTP
1
DELETE /api/v1/webhooks/{webhook_id}

Auth: API Key or Session

Test Webhook

Sends a test event to the webhook endpoint.

HTTP
1
POST /api/v1/webhooks/{webhook_id}/test

Auth: API Key or Session

Response (200 OK):

JSON
1
2
3
4
5
{
  "success": true,
  "status_code": 200,
  "response_time_ms": 145
}

Regenerate Webhook Secret

HTTP
1
POST /api/v1/webhooks/{webhook_id}/regenerate-secret

Auth: API Key or Session

List Webhook Deliveries

HTTP
1
GET /api/v1/webhooks/{webhook_id}/deliveries

Auth: API Key or Session

Retry Webhook Delivery

HTTP
1
POST /api/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/retry

Auth: API Key or Session

Get Webhook Stats

HTTP
1
GET /api/v1/webhooks/{webhook_id}/stats

Auth: API Key or Session

Get Global Webhook Stats

HTTP
1
GET /api/v1/webhooks/stats/global

Auth: API Key or Session

List Webhook Event Types

HTTP
1
GET /api/v1/webhooks/event-types

Auth: API Key or Session

Subscriber Notes API

Create Note

HTTP
1
POST /api/v1/subscribers/{subscriber_id}/notes

Auth: API Key or Session

List Notes

HTTP
1
GET /api/v1/subscribers/{subscriber_id}/notes

Auth: API Key or Session

Get Note

HTTP
1
GET /api/v1/subscribers/{subscriber_id}/notes/{note_id}

Auth: API Key or Session

Update Note

HTTP
1
PUT /api/v1/subscribers/{subscriber_id}/notes/{note_id}

Auth: API Key or Session

Delete Note

HTTP
1
DELETE /api/v1/subscribers/{subscriber_id}/notes/{note_id}

Auth: API Key or Session

API Keys API

List Available Scopes

HTTP
1
GET /api/v1/api-keys/scopes

Auth: API Key or Session

Create API Key

HTTP
1
POST /api/v1/api-keys

Auth: API Key or Session

Request Body:

JSON
1
2
3
4
{
  "name": "Production Backend",
  "scopes": ["subscribers:read", "subscribers:write", "tags:read"]
}

Response (201 Created):

JSON
1
2
3
4
5
6
7
{
  "id": "9fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Production Backend",
  "key": "sf_live_abc123xyz...",
  "scopes": ["subscribers:read", "subscribers:write", "tags:read"],
  "created_at": "2026-02-03T10:30:00Z"
}

API Key Storage

The full API key is only displayed once upon creation. Store it securely -- it cannot be recovered.

List API Keys

HTTP
1
GET /api/v1/api-keys

Auth: API Key or Session

Get API Key

HTTP
1
GET /api/v1/api-keys/{api_key_id}

Auth: API Key or Session

Update API Key

HTTP
1
PATCH /api/v1/api-keys/{api_key_id}

Auth: API Key or Session

Rotate API Key

HTTP
1
POST /api/v1/api-keys/{api_key_id}/rotate

Auth: API Key or Session

Delete API Key

HTTP
1
DELETE /api/v1/api-keys/{api_key_id}

Auth: API Key or Session

Preference Center API

Public endpoints for subscriber self-service. These endpoints use token-based authentication (JWT in query parameter).

Get Preferences

HTTP
1
GET /preference-center?token={jwt_token}

Response:

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "email": "user@example.com",
  "subscribed_tags": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Product Updates",
      "slug": "product-updates",
      "description": "Receive notifications about new features",
      "subscribed": true,
      "subscribed_at": "2026-01-15T10:30:00Z"
    }
  ],
  "available_tags": [
    {
      "id": "7ca85f64-5717-4562-b3fc-2c963f66afa9",
      "name": "Weekly Digest",
      "slug": "weekly-digest",
      "description": "Weekly summary",
      "subscribed": false
    }
  ]
}

Subscribe to Tag

HTTP
1
PUT /preference-center/tags/{tag_id}?token={jwt_token}

Unsubscribe from Tag

HTTP
1
DELETE /preference-center/tags/{tag_id}?token={jwt_token}

Request Data Export (GDPR)

HTTP
1
GET /preference-center/data-export?token={jwt_token}

Request Account Deletion (GDPR)

HTTP
1
DELETE /preference-center/account?token={jwt_token}

Billing API

Endpoints for subscription management and Stripe integration.

Get Current Subscription

HTTP
1
GET /api/v1/billing/subscription

Auth: API Key or Session (Owner only)

Response (200 OK):

JSON
1
2
3
4
5
6
7
8
9
{
  "tier": "starter",
  "status": "active",
  "current_period_end": "2026-03-03T00:00:00Z",
  "max_subscribers": 5000,
  "max_emails_per_month": 10000,
  "emails_sent_this_month": 1234,
  "subscriber_count": 450
}

Create Checkout Session

Creates a Stripe Checkout session for upgrading the subscription.

HTTP
1
POST /api/v1/billing/create-checkout-session

Auth: API Key or Session (Owner only)

Request Body:

JSON
1
2
3
{
  "price_id": "price_xxx"
}

Response (200 OK):

JSON
1
2
3
{
  "checkout_url": "https://checkout.stripe.com/..."
}

Customer Portal

Opens the Stripe Customer Portal for managing payment methods and invoices.

HTTP
1
POST /api/v1/billing/customer-portal

Auth: API Key or Session (Owner only)

Response (200 OK):

JSON
1
2
3
{
  "portal_url": "https://billing.stripe.com/..."
}

Sync Subscription

Manually syncs the subscription status from Stripe.

HTTP
1
POST /api/v1/billing/sync-subscription

Auth: API Key or Session (Owner only)

Email Settings API

Endpoints for managing organization email sending configuration.

Get Email Settings

HTTP
1
GET /api/v1/settings/email

Auth: API Key or Session

Response (200 OK):

JSON
1
2
3
4
5
6
7
8
9
{
  "from_name": "My Company",
  "from_address": "noreply@mycompany.com",
  "effective_from": "My Company <noreply@mycompany.com>",
  "is_custom_domain": true,
  "custom_domain": "mycompany.com",
  "custom_domain_status": "verified",
  "can_add_custom_domain": false
}

Update Email Settings

Update from_name (all tiers) or from_address (requires verified custom domain).

HTTP
1
PUT /api/v1/settings/email

Auth: API Key or Session

Request Body:

JSON
1
2
3
4
{
  "from_name": "My Company",
  "from_address": "noreply@mycompany.com"
}

Add Custom Domain

Start domain verification via Resend API. Professional tier only.

HTTP
1
POST /api/v1/settings/email/domain

Auth: API Key or Session

Request Body:

JSON
1
2
3
{
  "domain": "mycompany.com"
}

Response (201 Created):

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "domain": "mycompany.com",
  "status": "pending",
  "dns_records": [
    {
      "type": "TXT",
      "name": "_resend.mycompany.com",
      "value": "v=spf1 ..."
    }
  ]
}

Check Domain Verification

HTTP
1
GET /api/v1/settings/email/domain

Auth: API Key or Session

Remove Custom Domain

HTTP
1
DELETE /api/v1/settings/email/domain

Auth: API Key or Session

Response: 204 No Content

Platform Admin API

Endpoints for platform-level administration. Only accessible by organizations with is_platform_admin = true (currently only Talent Factory GmbH).

All endpoints require the RequirePlatformAdmin dependency, which verifies the requesting organization has platform admin privileges.

List Organizations

HTTP
1
GET /api/v1/admin/organizations

Auth: API Key or Session (Platform Admin only)

Get Organization

HTTP
1
GET /api/v1/admin/organizations/{organization_id}

Auth: API Key or Session (Platform Admin only)

Update Organization

HTTP
1
PATCH /api/v1/admin/organizations/{organization_id}

Auth: API Key or Session (Platform Admin only)

Delete Organization

HTTP
1
DELETE /api/v1/admin/organizations/{organization_id}

Auth: API Key or Session (Platform Admin only)

List Users

HTTP
1
GET /api/v1/admin/users

Auth: API Key or Session (Platform Admin only)

Get User

HTTP
1
GET /api/v1/admin/users/{user_id}

Auth: API Key or Session (Platform Admin only)

List Members of Organization

HTTP
1
GET /api/v1/admin/organizations/{organization_id}/members

Auth: API Key or Session (Platform Admin only)

Add Member to Organization

HTTP
1
POST /api/v1/admin/organizations/{organization_id}/members

Auth: API Key or Session (Platform Admin only)

Remove Member from Organization

HTTP
1
DELETE /api/v1/admin/organizations/{organization_id}/members/{user_id}

Auth: API Key or Session (Platform Admin only)

Incoming Webhooks

Resend Webhook

Receives webhook events from Resend (contact and email events).

HTTP
1
POST /webhooks/resend

Auth: HMAC SHA-256 signature (X-Resend-Signature header)

No API key required. Signature-verified only.

Stripe Webhook

Receives webhook events from Stripe (checkout, subscription, payment events).

HTTP
1
POST /webhooks/stripe

Auth: Stripe webhook signature

No API key required. Signature-verified only.

Health Endpoints

Basic Health Check

HTTP
1
GET /health

Response (200 OK):

JSON
1
2
3
{
  "status": "healthy"
}

Readiness Check

Checks database connection and Redis.

HTTP
1
GET /ready

Response (200 OK):

JSON
1
2
3
4
5
6
7
{
  "status": "ready",
  "checks": {
    "database": "ok",
    "redis": "ok"
  }
}

Error Responses

All errors follow the RFC 7807 Problem Details format:

JSON
1
2
3
4
5
6
7
{
  "type": "https://subscribeflow.net/errors/not_found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Subscriber with ID '550e8400...' not found",
  "instance": "/api/v1/subscribers/550e8400..."
}

See Error Codes Reference for the complete list.

SDKs

Python

Python
1
2
3
4
5
6
7
from subscribeflow import SubscribeFlowClient

async with SubscribeFlowClient(api_key="sf_live_xxx") as client:
    subscriber = await client.subscribers.create(
        email="user@example.com",
        tags=["product-updates"],
    )

TypeScript

TypeScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import { SubscribeFlowClient } from '@subscribeflow/sdk';

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

const subscriber = await client.subscribers.create({
  email: 'user@example.com',
  tags: ['product-updates'],
});

See SDK Setup Guide for details.

Further Reading