Docs / Start here
Troubleshooting
Common problems, what causes them and how to fix them. API errors have the form { "error": { "type", "code", "message" } }; the code is listed in each heading where there is one.
/ shows "The dashboard is not built"
The server cannot find apps/web/dist/index.html, so / shows a short page with build instructions and links to /docs and /openapi.json. The API works normally. npm run dev builds the dashboard before it starts, so this happens mainly with npm start or node apps/server/bin/onesend-server.mjs on a fresh checkout.
Build it and restart the server:
npm run build:web
Or run the development dashboard with npm run dev:web and open http://localhost:5199. If you keep the build somewhere else, set ONESEND_WEB_DIST to that folder.
The server stops at startup with an ONESEND_SECRET error
ONESEND_SECRET (or ONESEND_SECRET_FILE) is required when NODE_ENV=production. Production mode does not generate a secret. Set one:openssl rand -base64 32. The Docker image and.env.examplesetNODE_ENV=production.ONESEND_SECRET must be at least 32 characters. Generate a new value with the command above.ONESEND_SECRET is still the placeholder from .env.example. Replace the value with a generated one (openssl rand -base64 32). Values that look like placeholders (starting with<, or containinggenerate-with,changemeorplaceholder) are rejected, because a placeholder secret is public and anything encrypted with it would not be protected.Could not decrypt provider credentials — was ONESEND_SECRET changed?The secret differs from the one used to store the credentials. Restore the previous value, or set it asONESEND_SECRET_PREVIOUSand follow Rotating ONESEND_SECRET.
An email shows sent but never arrives
- Open the email in Logs, or call
GET /v1/emails/{id}, and check which provider carried it. - If the provider is
sandbox, nothing was delivered. A new workspace sends through the built-in Sandbox provider until you connect a real one. Connect a provider under Sending providers; Sandbox is then turned off in the default routing policy. If you edited the policy, check under Routing that Sandbox is not an enabled step. - If the status is
sandboxed, the email was sent with a test key (os_test_…) or with sandbox mode turned on for the workspace. Use a live key (os_live_…). - If a real provider accepted it, check the provider's own logs, the recipient's spam folder, and the domain's DNS under Senders & domains. Unverified domains and missing DKIM records are the most common cause of mail going to spam or being dropped.
Sign-up returns 403 signup_closed
ONESEND_SIGNUP defaults to first-user: only the first account on the instance can sign up. With closed, nobody can sign up over the network, and the owner account of a fresh instance must be created from the server itself (http://localhost:<port> on that machine, or through an SSH tunnel).
To add people to your workspace, invite them under Settings → Team → Invite: someone without an account creates one on the invitation page, whatever ONESEND_SIGNUP is (see Invitations). Set ONESEND_SIGNUP=open only when anyone who reaches the server may create an account; each such account gets its own workspace.
402 license_required
Live sends, campaigns and automations, and the workspace (inbox, calendar, booking pages, drive) need a license key on a self-hosted server. Test API keys, Sandbox mode and the dashboard work without one. Add the key under Settings → License, or set ONESEND_LICENSE_KEY before you start the server. The response's buyUrl links to the pricing page. See License key.
A port is already in use (EADDRINUSE)
The server stops when its HTTP port (PORT, default 3000) is taken. The mail ports are optional: when SMTP (2587, 2525), IMAP (1143) or POP3 (1110) is taken, the server logs an error for that port and keeps running without it. Stop the other program, choose another port, or turn the port off with 0: ONESEND_SMTP_PORT, ONESEND_SMTP_IN_PORT, ONESEND_IMAP_PORT and ONESEND_POP3_PORT (see Ports for the workspace). npm run doctor shows which ports are free.
401 unauthorized, invalid_api_key or invalid_session
unauthorized: the request has noAuthorizationheader (or no session cookie). SendAuthorization: Bearer os_live_….invalid_api_key: the key is unknown or has been revoked. Keys are shown only once when created; if a key is lost, create a new one under Developers → API keys and revoke the old one.invalid_session: the session token (oes_…) or dashboard session has expired. Sign in again.
403 insufficient_scope, session_required, test_mode, publishable_key or csrf_header_required
insufficient_scope: the key's permission does not cover the endpoint, for example a Read only key callingPOST /v1/emails, or a Sending only key managing contacts. Create a key with the permission you need. Sending only sends, Read only reads, and Full access covers the whole data plane (sending, reading and content such as templates, contacts and campaigns). Configuration (sending providers, routing, domains, webhooks, workspace settings, the license, team and API keys) needs an Admin key (live) or a signed-in admin.session_required: managing API keys needs a signed-in session or a live Admin key. See Authentication.publishable_key: Conversion tracking keys (os_pub_…) only work withPOST /t/conversionfrom the/t/onesend.jsscript. Use a secret key for the API.test_mode: test keys (os_test_…) cannot change settings, webhooks, sending providers, routing, domains, mailboxes, suppressions, templates, campaigns, contacts, lists or segments, read the inbox, manage API keys or send campaigns. Use a live key. See Authentication.csrf_header_required: a request authenticated with the dashboard cookie changed data without theX-OneSend-Client: dashboardheader. Scripts should use a bearer token instead of the cookie.
400 validation_failed
error.message describes each field that failed in a sentence, for example "Recipient has too many addresses: at most 50 in one field, and 100 across to, cc and bcc." error.details has one entry per problem with path, field, message and code. A field the endpoint does not accept is reported as "Unknown field: …". Send JSON bodies with Content-Type: application/json.
A campaign will not start: no_broadcast_provider
No active provider connection is allowed to send marketing email. Under Sending providers, open a provider whose terms permit marketing and turn on Use for campaigns.
SMTP clients cannot authenticate
Without ONESEND_SMTP_TLS_KEY and ONESEND_SMTP_TLS_CERT, SMTP ingress does not offer STARTTLS. Clients that require STARTTLS then fail, and AUTH is accepted only from clients on the same host. Configure TLS as described in SMTP. On a trusted private network you can instead set ONESEND_SMTP_ALLOW_INSECURE_AUTH=true. The SMTP password must be an API key with Full access or Sending only; the username can be anything.
413 payload_too_large, 415 unsupported_media_type or 429 rate_limited
payload_too_large: the request body is over the limit for that endpoint (1 MB by default, 15 MB for sending with attachments, 50 MB for CSV imports). See Request limits.unsupported_media_type: the body was not sent withContent-Type: application/json. CSV imports also acceptmultipart/form-data.rate_limited: too many login, sign-up or browser conversion requests from one client. Wait for the time in theRetry-Afterheader. Behind a reverse proxy, setONESEND_TRUST_PROXY=true(or the number of proxies), otherwise every client shares the proxy's limit.
A webhook, attachment URL or SMTP host on a private network is rejected
OneSend blocks requests to private, loopback and link-local addresses by default, to prevent server-side request forgery. Saving a webhook such as http://localhost:… returns 400 unsafe_url. If your webhook receiver, attachment host or self-hosted provider runs on your own network, set ONESEND_ALLOW_PRIVATE_NETWORK=true. For an SMTP relay on a private address, set ONESEND_ALLOW_PRIVATE_SMTP=true.
Emails stay deferred or queued
Every eligible provider has reached its daily or monthly limit, and the routing policy's fallback is queue_until_reset. The email is sent when a quota resets. Check Dashboard or GET /v1/analytics/quota, add a provider, or raise a connection's limit if the provider allows more. POST /v1/route/preview shows which providers are skipped and why.
Also check that the worker is running: ONESEND_WORKER=off disables it in that process.
The MCP server returns 401
The MCP server needs a OneSend API key: ONESEND_API_KEY for stdio, or an Authorization: Bearer header from the client in HTTP mode. Check that ONESEND_BASE_URL points at your server. A 403 "Host not allowed" in HTTP mode means the request's Host header is not accepted; behind a reverse proxy, set ONESEND_MCP_ALLOWED_HOSTS. See MCP.
Getting more detail
- Set
LOG_LEVEL=debugto log provider requests (credentials are redacted). - With
NODE_ENV=production, internal errors return "Something went wrong". The server log has the full error. GET /healthzreports whether the server and database are reachable.