---
title: "Getting started"
description: "OneSend sends email through the provider accounts you connect (Resend, Brevo, Amazon SES, Cloudflare, Mailgun, SMTP and others) and fails over to the next provider when one is unavailable or out of quota."
url: https://onesend.email/docs/getting-started/
---
# Getting started

OneSend sends email through the provider accounts you connect (Resend, Brevo, Amazon SES, Cloudflare, Mailgun, SMTP and others) and fails over to the next provider when one is unavailable or out of quota. This guide runs a server, connects a provider and sends a first email.

> OneSend is installed from the release you receive with your license, not from npm. Packages named `onesend` or `@onesend/*` on npm belong to other projects: do not install them. Use one of the options below.

## 1. Run the server

<a id="option-a-from-source"></a>
### Option A: from source

Requires Node.js 22.13 or later. No database server, Docker or Redis is needed.

```bash
git clone <repository-url> onesend   # replace <repository-url> with this repository's clone URL
cd onesend
npm install
npm run setup   # writes .env: environment, public URL, database, ports, sign-up mode, ONESEND_SECRET
npm run dev     # builds the dashboard, then starts the API, worker, SMTP and dashboard
```

<a id="configure"></a>
#### Configure with `npm run setup`

`npm run setup` explains what it does, then asks:

- **Where the server runs.** Local (`NODE_ENV=development`) or production (`NODE_ENV=production`, which hides internal error messages and requires `ONESEND_SECRET`).
- **Public URL.** `http://localhost:3000` locally; the public `https://` address in production. Links in sent email (tracking, unsubscribe, view in browser) and provider webhooks use it.
- **Database.** See [Where data is stored](#where-data-is-stored) below.
- **Ports.** HTTP (default 3000), SMTP sending (2587) and the inbound SMTP receiver (2525). `0` turns an SMTP port off. The server also opens IMAP (1143) and POP3 (1110) for [mail apps](https://onesend.email/docs/mail-clients/); set `ONESEND_IMAP_PORT=0` and `ONESEND_POP3_PORT=0` in `.env` to turn them off, or another port when one is taken (see [Ports for the workspace](https://onesend.email/docs/self-hosting/#ports-for-the-workspace)).
- **Who can create accounts.** `first-user` (default: only the owner), `open` (anyone; each account gets its own workspace), or `closed` (the owner signs up from the server itself).

It generates `ONESEND_SECRET` (32 random bytes) unless one exists, connects to the database with the real driver, creates the tables, and writes `.env` with permissions 0600. `.env` is ignored by git. Secrets are never printed, and database URLs are typed without echo and shown with the password removed. It ends with the next steps and how to back up.

Run it again to change a value: the current `.env` provides the defaults (press Enter to keep each one), only the changed keys are rewritten, and the previous file is kept as `.env.backup-<timestamp>`. If an earlier start already generated `./.data/secret`, setup copies that value into `.env`, so stored provider keys still decrypt.

Without questions, for scripts and CI:

```bash
npm run setup -- --yes                                    # SQLite in ./.data, local
DATABASE_URL='postgres://…' npm run setup -- --yes --env=production --db=postgres --public-url=https://mail.example.com
npm run setup -- --help                                   # every option
```

Pass the database URL in `DATABASE_URL` rather than `--database-url`, so the password stays out of your shell history.

Check the configuration at any time with `npm run doctor`. It changes nothing and prints a checklist: `.env` and its permissions, settings, `ONESEND_SECRET`, the database connection and migrations, accounts, sending providers, whether the server and its public URL answer, whether the HTTP and SMTP ports are free, and whether the dashboard is built. It exits with code 1 when something must be fixed.

<a id="where-data-is-stored"></a>
#### Where data is stored

Everything you create is stored in the database: accounts (passwords are hashed), workspaces and settings, provider credentials (encrypted with `ONESEND_SECRET`), domains, templates, contacts, campaigns, logs and the job queue.

| Choice in setup | What it is | Use it for |
|---|---|---|
| SQLite (default) | An embedded database in one file, `./.data/onesend.db`. Built into Node.js; nothing to install or run. | One server process: local use, and small or medium single-server installs. |
| PostgreSQL | Your own server, Neon, Supabase or Amazon RDS, given as a `postgres://` URL. | A hosted service, several server processes, managed backups. |
| Turso / libSQL | A `libsql://` URL and an auth token. | A hosted SQLite-compatible database. |
| PGlite | Embedded PostgreSQL in a local folder (`pglite:./.data/pg`). | Development and tests. |

The settings themselves are in `.env`; nothing is stored in the repository. Back up the database and `ONESEND_SECRET` together (see [Backups](https://onesend.email/docs/self-hosting/#backups)): a database backup cannot decrypt provider keys without the secret. To move to another database later, use `npm run db:copy` (see [Moving to another database](https://onesend.email/docs/self-hosting/#moving-to-another-database)).

Skipping `npm run setup` works too: with no `.env` and no `DATABASE_URL`, the server uses SQLite in `./.data` and generates a secret in `./.data/secret` on its first start.

#### Running

`npm run dev` builds the dashboard into `apps/web/dist`, then starts the server from the repository root and restarts it when source files change. To run without the file watcher, use `npm start`. It uses the same `.env` and `./.data` folder, so both commands show the same instance. `npm start` does not build the dashboard; run `npm run build:web` first.

The server loads `.env` from the folder it starts in. Variables already set in the environment (your shell, Docker, systemd or your platform) win over the file. Set `ONESEND_ENV_FILE=<path>` to read another file, or `ONESEND_ENV_FILE=off` to read none. Secrets can also come from `<NAME>_FILE` (for example `ONESEND_SECRET_FILE=/run/secrets/onesend_secret`); they are never accepted in `onesend.config.json`.

When something is wrong at startup, the server stops with a sentence that says what to change, for example `ONESEND_SECRET is not set, and it is required when NODE_ENV=production. Run "npm run setup" …`, or `Could not open the database: PostgreSQL (postgres://***@db.example.com:5432/app). Nothing is listening at that host and port …`. Database passwords are never printed.

Earlier versions of `npm run dev` kept data in `apps/server/.data`. To keep that data, stop the server and move the folder: `mv apps/server/.data .data` (or set `ONESEND_DATA_DIR=apps/server/.data`).

If the dashboard has not been built, `/` shows a page saying so, with links to `/docs` and `/openapi.json`. Build it with `npm run build:web`, or run the development dashboard with `npm run dev:web` in a second terminal and open http://localhost:5199 (set `ONESEND_WEB_PORT` to use another port). The development dashboard proxies `/v1`, `/docs` and the other API paths to `http://localhost:3000`; if the server runs elsewhere, start it with `ONESEND_API=http://localhost:<port> npm run dev:web`.

<a id="option-b-docker"></a>
### Option B: Docker

The repository includes a `Dockerfile`, `docker-compose.yml` (SQLite on a volume) and `docker-compose.postgres.yml` (adds PostgreSQL). The image is built from your copy of OneSend. Secrets are never written into the compose files.

SQLite:

```bash
cp .env.example .env
# Replace the ONESEND_SECRET placeholder with a generated value:
sed -i.bak "s|^ONESEND_SECRET=.*|ONESEND_SECRET=$(openssl rand -base64 32)|" .env
# For a real deployment, set ONESEND_PUBLIC_URL=https://<your host> in .env (unset means http://localhost:3000).
docker compose up -d --build
```

PostgreSQL:

```bash
cp .env.example .env
sed -i.bak "s|^ONESEND_SECRET=.*|ONESEND_SECRET=$(openssl rand -base64 32)|" .env
echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" >> .env
set -a; . ./.env; set +a
mkdir -p secrets
printf 'postgres://onesend:%s@postgres:5432/onesend' "$POSTGRES_PASSWORD" > secrets/database_url
docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d --build
```

Keep `POSTGRES_PASSWORD` in `.env`: Compose reads it on every start, and the database keeps the password it was created with. `secrets/` and `.env` are excluded from git. Back up `ONESEND_SECRET`; see [Backups](https://onesend.email/docs/self-hosting/#backups).

Instead of editing `.env` by hand, you can write it with `npm run setup -- --env=production --skip-db-check` on the host (Node.js needed). Keep `PORT=3000` for the bundled Compose file; the container keeps SQLite in `/data` whatever `ONESEND_DATA_DIR` says in `.env`.

See the [self-hosting reference](https://onesend.email/docs/self-hosting/) for every variable.

## 2. Create your account

Open http://localhost:3000. A new server has no account yet, so the dashboard shows **Create the owner account**, with a note on where the data is stored (the database kind comes from the unauthenticated `GET /v1/setup/status`, which returns no paths, hosts or secrets). The first account becomes the owner. Later sign-ups follow `ONESEND_SIGNUP` (default `first-user`: no further accounts). Create the owner account before you expose a new instance to the internet: until then, anyone who reaches it can sign up as owner.

After sign-up, a short checklist connects a provider, adds a domain, sends a test email and creates an API key. Each step can be skipped and done later from the dashboard.

<a id="sandbox"></a>
**Sandbox provider.** A new workspace includes a **Sandbox** provider so the first API call succeeds before you connect anything. Sandbox accepts every email and delivers none: an email sent through it shows status `sent` with provider `sandbox` in **Logs**, but no message leaves the server. When you connect a real provider, Sandbox is turned off in the default routing policy. Sandbox can also simulate outages, quota exhaustion and bounces; see [Sandbox mode](https://onesend.email/docs/concepts/#sandbox-mode).

## 3. Connect providers

Open **Sending providers** and select **Connect provider**. Pick Resend, Brevo, Cloudflare or another provider and paste that provider's API key. OneSend checks the key, reads the quota when the provider exposes it (otherwise it uses the known free tier, which you can change), and adds the provider to your default routing policy.

Set the order under **Routing**, for example Resend (cap 99 per day), then Brevo (cap 295 per day), then Cloudflare. The **Dashboard** page shows the combined capacity left today.

## 4. Add your domain

Open **Senders & domains** and select **Add domain**, for example `acme.dev`. OneSend registers the domain with every connected provider that supports it and merges their DNS records into one plan. If the domain's DNS is on Cloudflare and you connected Cloudflare with DNS permission, OneSend can write the records for you. Otherwise copy the table or download the zone file. See [Domains and DNS](https://onesend.email/docs/domains-and-dns/).

## 5. Create an API key and send

Open **Developers → API keys** and select **Create key**. Choose the permission (**Full access**, **Sending only**, **Read only** or **Conversion tracking**) and the mode: **Live** keys (`os_live_…`) send through your providers, and **Test** keys (`os_test_…`) log email without delivering it. The full key is shown once. See [Authentication](https://onesend.email/docs/api/#authentication) for what each permission allows.

Send the template's slug and its variables:

```bash
export ONESEND_API_KEY=os_live_...
curl -X POST http://localhost:3000/v1/emails \
  -H "Authorization: Bearer $ONESEND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-42" \
  -d '{"from":"Acme <hi@acme.dev>","to":"ada@example.com","template":"welcome-email","variables":{"first_name":"Ada","company":"Acme"}}'
```

The response is `{ "id": "msg_…", "status": "queued" }`. The worker then routes the email through your policy.

`welcome-email` is the gallery template **Welcome email** copied into your workspace. Add it under **Templates → Template gallery**, or with `POST /v1/gallery/welcome-folio/clone` and `{ "slug": "welcome-email" }`. OneSend renders the template with your variables and gives each provider finished HTML, so one template works with every provider, including when an email fails over to another provider, and you can edit the template in the dashboard without changing your code. Missing variables are listed in the response as `warnings`.

For a one-off email without a template, send `subject` and `html` (or `text`) instead of `template` and `variables`:

```bash
curl -X POST http://localhost:3000/v1/emails \
  -H "Authorization: Bearer $ONESEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"Acme <hi@acme.dev>","to":"ada@example.com","subject":"Welcome","html":"<p>Hello</p>"}'
```

With the TypeScript SDK, from inside this repository (see [SDK and CLI](https://onesend.email/docs/sdk-and-cli/) for use from another project):

```ts
import { OneSend } from '@onesend/sdk'; // the workspace package in packages/sdk
const onesend = new OneSend({ apiKey: process.env.ONESEND_API_KEY, baseUrl: 'http://localhost:3000' });
await onesend.emails.send({ from: 'hi@acme.dev', to: 'ada@example.com', template: 'welcome-email', variables: { first_name: 'Ada' } });
```

Save it as `send.ts` inside the repository and run `npx tsx send.ts`. Plain `node` cannot load the SDK's TypeScript source.

Open **Logs** to see the route the email took: each provider tried, why it was skipped or failed, and which provider delivered it.

If the email shows `sent` but never arrives, check that it did not go through Sandbox (see [Troubleshooting](https://onesend.email/docs/troubleshooting/#sent-but-not-delivered)).

<a id="try-the-inbox-locally"></a>
## Try the inbox locally

Receiving mail needs a verified domain, which a local machine normally cannot prove. For development, `ONESEND_DNS_OVERRIDES` answers OneSend's DNS checks for a test domain (it is refused when `NODE_ENV=production`):

```bash
ONESEND_DNS_OVERRIDES='{"acme.test":"*"}' npm run dev
```

1. Under **Senders & domains**, add `acme.test` with inbound set to the built-in receiver, then select **Check DNS**. Every record OneSend checks under `acme.test` is answered as expected, so the domain verifies.
2. Under **Inbox**, create an address such as `support@acme.test`.
3. Send a message to the built-in receiver on port 2525, for example with [swaks](https://jetmore.org/john/code/swaks/): `swaks --server localhost:2525 --to support@acme.test --from ada@example.com`.

The message appears in **Inbox**. See [Testing domains locally](https://onesend.email/docs/domains-and-dns/#testing-locally) for exact answers per record.

## Next steps

- Marketing campaigns, contacts and CSV import: [Marketing](https://onesend.email/docs/marketing/)
- Receive events in your app: [Webhooks](https://onesend.email/docs/webhooks/)
- Use OneSend from an AI client: [MCP](https://onesend.email/docs/mcp/)
- Apps that only support SMTP (WordPress, Ghost, Supabase Auth): [SMTP](https://onesend.email/docs/smtp/)
- Templates: [Templates and gallery](https://onesend.email/docs/templates/)
- Production setup, backups and upgrades: [Self-hosting](https://onesend.email/docs/self-hosting/)
