Skip to content

Authentication

Every request to the SubscribeFlow API requires an API key.

API key format

Prefix Environment Purpose
sf_live_ Production Real subscribers, real emails
sf_test_ Testing Sandbox data, no emails sent

Create keys in the Dashboard under Settings > API Keys.

Warning

API keys are shown only once at creation. Store them securely -- you cannot retrieve them later.

Sending your API key

Include the key in every request using one of these headers:

X-API-Key: sf_live_...

Authorization: Bearer sf_live_...

Example authenticated request

from subscribeflow import SubscribeFlowClient

async with SubscribeFlowClient(api_key="sf_live_...") as client:
    subscribers = await client.subscribers.list(limit=10)

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

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

const { items } = await client.subscribers.list({ limit: 10 });

curl https://api.subscribeflow.net/api/v1/subscribers?limit=10 \
  -H "X-API-Key: sf_live_..."

Scopes

Each API key can be restricted to specific scopes. If no scopes are set, the key has full access.

Scope Description
subscribers:read List and get subscribers
subscribers:write Create and update subscribers
subscribers:delete Delete subscribers
tags:read List and get tags
tags:write Create, update, and delete tags
templates:read List and get email templates
templates:write Create, update, and delete templates
emails:send Send transactional emails
campaigns:read List and get campaigns
campaigns:write Create, update, send, and cancel campaigns
triggers:read List and get email triggers
triggers:write Create, update, and delete triggers
webhooks:manage Create, update, delete, and test webhooks
api-keys:manage Create and revoke API keys

Tip

Follow the principle of least privilege. A key that only sends emails should have the emails:send scope and nothing else.

Rate limits

All API keys are rate-limited to 1,000 requests per minute. When you exceed this limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

from subscribeflow import RateLimitError

try:
    await client.subscribers.list()
except RateLimitError:
    print("Rate limit hit -- wait and retry")

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

try {
  await client.subscribers.list();
} catch (error) {
  if (error instanceof SubscribeFlowError && error.status === 429) {
    console.log('Rate limit hit -- wait and retry');
  }
}

# Check rate limit headers in the response:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 998
# X-RateLimit-Reset: 1710000060