Quickstart

Using an AI agent? Add the MCP server and say “set me up”: it does every step below for you. In the TUI, 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. Install the CLI and sign in. A browser opens once to confirm.

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

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

Run subscriber, then choose a workspace and an environment. Press n to create either.

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:

KEY=$(subscriber keys create "Quickstart" --access full)

The key decides the environment, so requests don’t name it. See 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.

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.

Open Integrations, press n, choose SMTP or Cloudflare Email, and fill in the form.

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

Save this as welcome.json:

welcome.json

{
  "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>"
    }
  ]
}

subscriber workflows create --file welcome.json

Open Workflows, press n, and fill in the key, name and steps. Each step is an email or a webhook, with an optional delay.

With the same welcome.json as the CLI tab:

curl -X POST https://api.subscriber.dev/workflows \
  -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d @welcome.json

See Workflows and Templates 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.

subscriber subscribers create --email jane@acme.com --first-name Jane
subscriber workflows trigger welcome --email jane@acme.com

Open Subscribers and press n to add Jane. Then open Workflows, choose Welcome, press t and enter her email.

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

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.

subscriber workflows runs <workflowId>

Open Workflows, choose Welcome and press r to see its runs. Run History shows runs across every workflow.

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

Connect your AI agent

Let your agent write workflows and manage subscribers for you.

Start workflows from Stripe

Send trial and payment emails automatically.

Get started

Tools

Guides

Integrations

API reference

Self-hosting

2. Pick a workspace and environment

3. Connect your email provider

4. Create a workflow

5. Add a subscriber and trigger the workflow

6. Check it sent

Next steps

Connect your AI agent

Start workflows from Stripe

​1. Sign in

​2. Pick a workspace and environment

​3. Connect your email provider

​4. Create a workflow

​5. Add a subscriber and trigger the workflow

​6. Check it sent

​Next steps

Connect your AI agent

Start workflows from Stripe

1. Sign in

2. Pick a workspace and environment

3. Connect your email provider

4. Create a workflow

5. Add a subscriber and trigger the workflow

6. Check it sent

Next steps