Docs / Start here
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
onesendor@onesend/*on npm belong to other projects: do not install them. Use one of the options below.
1. Run the server
Option A: from source
Requires Node.js 22.13 or later. No database server, Docker or Redis is needed.
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
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 requiresONESEND_SECRET). - Public URL.
http://localhost:3000locally; the publichttps://address in production. Links in sent email (tracking, unsubscribe, view in browser) and provider webhooks use it. - Database. See Where data is stored below.
- Ports. HTTP (default 3000), SMTP sending (2587) and the inbound SMTP receiver (2525).
0turns an SMTP port off. The server also opens IMAP (1143) and POP3 (1110) for mail apps; setONESEND_IMAP_PORT=0andONESEND_POP3_PORT=0in.envto turn them off, or another port when one is taken (see Ports for the workspace). - Who can create accounts.
first-user(default: only the owner),open(anyone; each account gets its own workspace), orclosed(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:
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.
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): 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).
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.
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:
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:
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.
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 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.
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.
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.
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 for what each permission allows.
Send the template's slug and its variables:
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:
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 for use from another project):
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).
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):
ONESEND_DNS_OVERRIDES='{"acme.test":"*"}' npm run dev
- Under Senders & domains, add
acme.testwith inbound set to the built-in receiver, then select Check DNS. Every record OneSend checks underacme.testis answered as expected, so the domain verifies. - Under Inbox, create an address such as
support@acme.test. - Send a message to the built-in receiver on port 2525, for example with swaks:
swaks --server localhost:2525 --to support@acme.test --from ada@example.com.
The message appears in Inbox. See Testing domains locally for exact answers per record.
Next steps
- Marketing campaigns, contacts and CSV import: Marketing
- Receive events in your app: Webhooks
- Use OneSend from an AI client: MCP
- Apps that only support SMTP (WordPress, Ghost, Supabase Auth): SMTP
- Templates: Templates and gallery
- Production setup, backups and upgrades: Self-hosting