Skip to main content
The REST API is how your app talks to subscriber.dev, for example to add a subscriber and trigger a welcome email when someone signs up. The CLI and MCP server use the same API.

​
Base URL

If you self-host, use your own API URL instead.

​
Authentication

Send an API key in the x-api-key header.
Create one with the CLI, or ask your agent:
The key is only shown once, so store it as a secret straight away, for example as SUBSCRIBER_API_KEY. Keep it on your server: never put it in frontend code or commit it. Each key belongs to one environment, and requests made with it use that environment, so you never pass its ID. A staging key can’t touch production. To check which environment a key belongs to, call GET /keys/me. Any key can call it.

​
Access

By default a key is limited: it can trigger workflows and create or update subscribers, which is what your app needs. That keeps a leaked key from reading your subscribers or changing your workflows. Pass --access full for a key that can call every endpoint below, or pick scopes yourself with --scope: A few endpoints need you signed in, not an API key: managing workspaces, environments, API keys and your plan. Use the CLI or your agent for those. To revoke a key, run subscriber keys revoke <keyId>. Requests made with it fail straight away.

​
Response codes

Subscriber.dev uses standard HTTP codes to indicate the success or failure of your requests. In general, 2xx HTTP codes correspond to success, 4xx codes are for user-related failures, and 5xx codes are for infrastructure issues.

​
Rate limits

Each API key, or agent signed in through MCP, can make 10 requests a second. Each IP address can make 20 requests a second across all of them. Over the limit, you get a 429. Wait a second and try again. To add many subscribers at once, use the bulk endpoint, which takes 500 per request. Inbound webhooks from email providers and Stripe have a higher limit, so a burst of bounces after a big broadcast isn’t dropped.