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

# Quickstart

> Send your first workflow email in about five minutes.

> [!TIP]
>
> Using an AI agent? [Add the MCP server](https://docs.subscriber.dev/mcp.md) and say "set me up": it does every step below for you. In the [TUI](https://docs.subscriber.dev/tui.md#get-started), run `subscriber` and it walks you through them.

The steps below use the CLI, the TUI or the REST API. Pick a tab on any step and the rest follow.

## 1. Sign in

Install the CLI and sign in. A browser opens once to confirm.

```bash theme={null}
npm install -g @subscriber.dev/cli
subscriber login
```

The CLI saves your session in `~/.config/subscriber/config.json`. It needs Node.js 22.12 or later.

Your AI agent doesn't need it: [the MCP server](https://docs.subscriber.dev/mcp.md) signs in through your browser. To use the TUI, run `subscriber` with no arguments.

## 2. Pick a workspace and environment

A workspace is your team's account. Inside it, environments keep separate sets of data, such as production and staging, so testing never emails real people. Every workspace starts with a **Production** environment.

> [tab] CLI
>
> ```bash theme={null}
> subscriber workspaces list
> subscriber workspaces use <workspaceId>
> subscriber environments list
> subscriber environments use <environmentId>
> ```
>
> Later commands run against the workspace and environment you picked. Create a workspace with `subscriber workspaces create "Acme"`.

> [tab] TUI
>
> Run `subscriber`, then choose a workspace and an environment. Press `n` to create either.

> [tab] API
>
> Pick the environment with the CLI, as in the CLI tab, then create an API key for it. A `full` key can do every step below:
>
> ```bash theme={null}
> KEY=$(subscriber keys create "Quickstart" --access full)
> ```
>
> The key decides the environment, so requests don't name it. See [Authentication](https://docs.subscriber.dev/api-reference/introduction.md#authentication) for what keys can do.

## 3. Connect your email provider

Subscriber.dev sends through your own provider, so you keep your sending reputation and pay them directly. It works with any SMTP provider, or Cloudflare Email.

> [tab] CLI
>
> ```bash theme={null}
> subscriber integrations set smtp --body '{
>   "host": "smtp.resend.com",
>   "port": 465,
>   "secure": true,
>   "fromEmail": "hello@acme.com",
>   "fromName": "Acme",
>   "user": "resend",
>   "password": "re_..."
> }'
> ```
>
> For Cloudflare Email, use `subscriber integrations set cloudflare` with `accountId`, `apiToken`, `fromEmail` and `fromName`.

> [tab] TUI
>
> Open **Integrations**, press `n`, choose **SMTP** or **Cloudflare Email**, and fill in the form.

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://api.subscriber.dev/integrations/smtp \
>   -H "x-api-key: $KEY" -H "content-type: application/json" \
>   -d '{"host": "smtp.resend.com", "port": 465, "secure": true, "fromEmail": "hello@acme.com", "fromName": "Acme", "user": "resend", "password": "re_..."}'
> ```

The connection is checked before it's saved, and credentials are encrypted at rest. See [Sending](https://docs.subscriber.dev/sending.md) for other providers and how to stay out of the spam folder.

## 4. Create a workflow

This one sends a welcome email straight away and a follow-up two days later.

> [tab] CLI
>
> Save this as `welcome.json`:
>
> ```json welcome.json theme={null}
> {
>   "key": "welcome",
>   "name": "Welcome",
>   "steps": [
>     {
>       "type": "email",
>       "subject": "Welcome to Acme",
>       "body": "<p>Hey {{ subscriber.firstName | default: \"there\" }},</p><p>Thanks for signing up.</p><p><a class=\"button\" href=\"https://acme.com/start\">Get started</a></p>"
>     },
>     {
>       "type": "email",
>       "delayMs": 172800000,
>       "subject": "How's it going?",
>       "body": "<p>Just checking in. Reply to this email if you're stuck.</p>"
>     }
>   ]
> }
> ```
>
> ```bash theme={null}
> subscriber workflows create --file welcome.json
> ```

> [tab] TUI
>
> Open **Workflows**, press `n`, and fill in the key, name and steps. Each step is an email or a webhook, with an optional delay.

> [tab] API
>
> With the same `welcome.json` as the CLI tab:
>
> ```bash theme={null}
> curl -X POST https://api.subscriber.dev/workflows \
>   -H "x-api-key: $KEY" -H "content-type: application/json" \
>   -d @welcome.json
> ```

See [Workflows](https://docs.subscriber.dev/workflows.md) and [Templates](https://docs.subscriber.dev/templates.md) for everything a workflow can do.

## 5. Add a subscriber and trigger the workflow

A subscriber is someone you email. Triggering a workflow starts it for one subscriber, which is what your app would do when someone signs up.

> [tab] CLI
>
> ```bash theme={null}
> subscriber subscribers create --email jane@acme.com --first-name Jane
> subscriber workflows trigger welcome --email jane@acme.com
> ```

> [tab] TUI
>
> Open **Subscribers** and press `n` to add Jane. Then open **Workflows**, choose **Welcome**, press `t` and enter her email.

> [tab] API
>
> In production you'll usually do this from your app's code, right after signup. Give your app a `limited` key, which can only add subscribers and trigger workflows: `subscriber keys create "Acme app"`.
>
> ```ts theme={null}
> const api = "https://api.subscriber.dev";
> const headers = {
>   "x-api-key": process.env.SUBSCRIBER_API_KEY,
>   "content-type": "application/json",
> };
>
> await fetch(`${api}/subscribers`, {
>   method: "POST",
>   headers,
>   body: JSON.stringify({ email: user.email, firstName: user.firstName }),
> });
>
> await fetch(`${api}/workflows/trigger`, {
>   method: "POST",
>   headers,
>   body: JSON.stringify({ key: "welcome", subscriber: { email: user.email } }),
> });
> ```

The subscriber has to exist before you trigger a workflow for them. To bring in existing subscribers, use `subscriber subscribers bulk` or ask your agent to import an export.

## 6. Check it sent

Each time a workflow is triggered it creates a run, which records what sent and what's still waiting.

> [tab] CLI
>
> ```bash theme={null}
> subscriber workflows runs <workflowId>
> ```

> [tab] TUI
>
> Open **Workflows**, choose **Welcome** and press `r` to see its runs. **Run History** shows runs across every workflow.

> [tab] API
>
> ```bash theme={null}
> curl https://api.subscriber.dev/workflows/$WORKFLOW/runs -H "x-api-key: $KEY"
> ```

Each run shows its status and which steps have sent.

## Next steps

> [card] [Connect your AI agent](https://docs.subscriber.dev/mcp.md)
>
> Let your agent write workflows and manage subscribers for you.

> [card] [Start workflows from Stripe](https://docs.subscriber.dev/integrations/stripe.md)
>
> Send trial and payment emails automatically.


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