Subscriber Management¶

Manage subscribers and their preferences via the API. All subscribers are scoped to the organization associated with the API key used for authentication.

Organization Scope

Every subscriber belongs to exactly one organization. The organization_id is automatically determined from your API key -- you never need to specify it explicitly. All list, get, update, and delete operations are filtered to your organization's subscribers only.

Subscriber Limits by Tier¶

Tier	Subscriber Limit
Free	500
Starter	5,000
Professional	50,000

Exceeding the subscriber limit returns a 403 Forbidden with error code limit_exceeded.

Creating a Subscriber¶

MinimalWith ProfileWith Tags

Bash
curl -X POST /api/v1/subscribers \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Bash
curl -X POST /api/v1/subscribers \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "first_name": "Max",
    "last_name": "Mustermann",
    "metadata": {
      "customer_id": "cust_123",
      "plan": "pro"
    }
  }'

Bash
curl -X POST /api/v1/subscribers \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "tags": ["product-updates", "weekly-digest"]
  }'

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

Retrieving Subscribers¶

Single Subscriber¶

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

Only returns the subscriber if it belongs to your organization.

By Email¶

Bash
curl "/api/v1/subscribers?email=user@example.com" \
  -H "X-API-Key: $API_KEY"

List with Filters¶

Bash
# Active subscribers with a specific tag
curl "/api/v1/subscribers?status=active&tag=product-updates&per_page=50" \
  -H "X-API-Key: $API_KEY"

All list queries are automatically filtered to your organization's subscribers.

Updating a Subscriber¶

Bash
curl -X PATCH /api/v1/subscribers/:id \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Maximilian",
    "metadata": {
      "plan": "enterprise"
    }
  }'

Partial Updates

PATCH requests only update the specified fields. Fields not included remain unchanged.

Managing Tags¶

Adding Tags¶

Bash
curl -X PATCH /api/v1/subscribers/:id/tags \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add": ["new-tag-1", "new-tag-2"]
  }'

Removing Tags¶

Bash
curl -X PATCH /api/v1/subscribers/:id/tags \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remove": ["old-tag"]
  }'

Replacing Tags¶

Bash
curl -X PUT /api/v1/subscribers/:id/tags \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["only-these-tags"]
  }'

Status Management¶

Status Values¶

stateDiagram-v2
    [*] --> active: Subscriber created
    active --> unsubscribed: Unsubscribe
    active --> bounced: Bounce Event
    active --> complained: Spam Complaint
    unsubscribed --> active: Resubscribe
    bounced --> active: Email corrected

Status	Description	Receives Emails
`active`	Active subscriber	Yes
`unsubscribed`	Unsubscribed	No
`bounced`	Email undeliverable	No
`complained`	Spam complaint	No

Changing Status¶

Bash
# Manual unsubscribe
curl -X PATCH /api/v1/subscribers/:id \
  -H "X-API-Key: $API_KEY" \
  -d '{"status": "unsubscribed"}'

# Resubscribe
curl -X PATCH /api/v1/subscribers/:id \
  -H "X-API-Key: $API_KEY" \
  -d '{"status": "active"}'

Bulk Operations¶

Bulk Import¶

Bash
curl -X POST /api/v1/subscribers/import \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribers": [
      {"email": "user1@example.com", "tags": ["newsletter"]},
      {"email": "user2@example.com", "tags": ["newsletter"]}
    ],
    "update_existing": true
  }'

Tier Limits

Bulk imports that would exceed your tier's subscriber limit will be partially rejected. The response indicates which subscribers were created and which were skipped.

Bulk Tag Update¶

Bash
curl -X POST /api/v1/subscribers/bulk-tag \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"tag": "old-category"},
    "add_tags": ["new-category"],
    "remove_tags": ["old-category"]
  }'

Deleting a Subscriber¶

Soft Delete¶

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

Bash
curl -X DELETE /api/v1/subscribers/:id?permanent=true \
  -H "X-API-Key: $API_KEY"

Permanent Delete

With permanent=true, all data is irrevocably deleted, including history. This is intended for GDPR deletion requests.

Subscription History¶

Retrieve the change history:

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

Response:

JSON
{
  "data": [
    {
      "action": "subscribe",
      "tag": "product-updates",
      "source": "preference_center",
      "changed_at": "2024-01-15T10:30:00Z"
    },
    {
      "action": "unsubscribe",
      "tag": "weekly-digest",
      "source": "api",
      "changed_at": "2024-01-14T08:00:00Z"
    }
  ]
}

Best Practices¶

Double opt-in: Confirm new subscribers via email
Use metadata: Store relevant contextual data
Tags over status: Use tags for segmentation
Check history: Consult the history for support inquiries
Monitor limits: Track subscriber count against your tier limit via GET /api/v1/billing/usage