> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subscriber.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Call subscriber.dev from your own app.

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

```
https://api.subscriber.dev
```

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

## Authentication

Send an API key in the `x-api-key` header.

```
x-api-key: <your API key>
```

Create one with the [CLI](https://docs.subscriber.dev/cli.md#api-keys), or ask your [agent](https://docs.subscriber.dev/mcp.md):

```bash theme={null}
subscriber keys create "Acme app"
```

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`:

| Scope | Allows |
| - | - |
| `workflows:trigger` | Trigger workflows |
| `workflows:read` | List workflows, their runs and trigger sources |
| `workflows:write` | Create, update and delete workflows |
| `broadcasts:read` | List broadcasts and preview their audience |
| `broadcasts:write` | Send, pause, resume and cancel broadcasts |
| `subscribers:read` | List and get subscribers and tags |
| `subscribers:write` | Create, update and delete subscribers, their tags and preferences |
| `emails:test` | Preview emails and send test emails |
| `integrations:read` | List email providers and other integrations |
| `integrations:write` | Connect, change and remove integrations |
| `uploads:write` | Upload images for emails |
| `events:read` | List inbound events |
| `analytics:read` | Read analytics and the setup checklist |
| `billing:read` | Read the workspace's plan and usage |

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.

| Status | Description |
| - | - |
| `200` | Success |
| `400` | Invalid parameters |
| `401` | Missing or invalid API key |
| `403` | The key doesn't have the scope this endpoint needs |
| `404` | Resource not found |
| `429` | Too many requests |
| `500` | Error with our infrastructure |

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.