Docs / Running it yourself
Cloudflare edition
OneSend can run entirely on Cloudflare, with no server of your own. One Worker (apps/worker-cf) does everything the Node server does over HTTP:
| Part | Cloudflare product | Binding |
|---|---|---|
API (/v1), API reference (/docs), provider webhooks, tracking and unsubscribe links | Workers | |
| Database | D1 | DB (required) |
| Jobs: sending, retries, webhooks, campaigns, imports, domain checks | Queues, with a Cron Trigger as the fallback | JOBS (optional) |
| Periodic jobs: maintenance, statistics rollup, snooze and inbox sweep, domain ownership re-checks | Cron Trigger (every minute) | |
| Attachment bytes, mail import uploads, drive files | R2 | FILES (optional for sending; required for the drive and mail import) |
| Dashboard | Workers Static Assets (apps/web/dist) | ASSETS |
| Receiving mail into the workspace's inbox | Email Routing, delivered to the same Worker's email() handler | |
| Inbox, calendar, booking pages, drive | The same Worker (the workspace module, without its Node listeners) |
It is the same application code as the Node server (apps/server). The parts that need a long-running process, raw TCP sockets or a filesystem are switched off. See What is not available.
What you need
- A Cloudflare account, on the Workers Paid plan. It costs at least $5 per month per account. The Free plan does not work for OneSend. It allows 10 ms of CPU per request, and hashing a password at sign-in takes longer than that. It also allows 50 D1 queries per invocation, and creating an account or sending a campaign uses more. Paid allows 30 seconds of CPU by default (up to 5 minutes) and 1,000 D1 queries per invocation.
- Node.js 22.13 or later, and a clone of this repository with
npm installdone. Wrangler is installed as a dev dependency ofapps/worker-cf. - Wrangler logged in to your account:
npx wrangler login, or setCLOUDFLARE_API_TOKEN. The scripts never log in for you. - To use your own domain and to receive mail: a domain whose DNS is on Cloudflare.
- R2 enabled once on the account (dashboard → R2 → Get started). R2 is optional.
Prices and limits that matter here. These were checked on 2026-11-08 at developers.cloudflare.com (Workers, D1, Queues and R2 pricing and limits pages). Check those pages for current values.
| Workers Free | Workers Paid | |
|---|---|---|
| Price | $0 | $5 per month minimum; 10 million requests and 30 million CPU ms included |
| CPU per request | 10 ms | 30 s by default, configurable up to 5 min |
| D1 queries per Worker invocation | 50 | 1,000 |
| D1 database size | 500 MB | 10 GB per database (cannot be raised); 1 TB per account |
| D1 rows read / written | 5 million / 100,000 per day | 25 billion / 50 million per month included, then $0.001 / $1.00 per million |
| D1 storage | 5 GB total | 5 GB included, then $0.75 per GB-month |
| D1 Time Travel (point-in-time restore) | 7 days | 30 days |
| Queues | 10,000 operations per day | 1 million operations per month included, then $0.40 per million |
| R2 (both plans) | 10 GB-month storage, 1 million Class A and 10 million Class B operations per month free; no egress fees | same |
What you pay. Three separate costs: the OneSend license key, one payment for one installation (one Cloudflare account counts as one installation; see the pricing page); the Workers Paid plan, billed by Cloudflare to your account each month (at least $5, plus any usage above the included amounts in the table); and your sending providers, billed by each provider under its own plan. OneSend adds no per-email or per-contact fee. Cloudflare Email Service as a sending provider is part of your Cloudflare bill; see Cloudflare's Email Service pricing page for its current price.
Quick start
From the repository root:
npx wrangler login
npm run cf:setup # creates D1 + Queue + R2, writes apps/worker-cf/wrangler.jsonc, stores ONESEND_SECRET
npm run cf:deploy # builds the dashboard and the gallery snapshot, then deploys the Worker
Then open the URL that wrangler deploy prints (https://onesend.<your-subdomain>.workers.dev). Create the owner account straight away. With the default ONESEND_SIGNUP=first-user, the first person to sign up becomes the owner, and the URL is public from the moment it is deployed. So cf:setup also stores a one-time setup code (ONESEND_SETUP_CODE) and prints it: the sign-up page asks for it, and nobody without it can create the owner. Once the owner exists the code is ignored; you can remove it with npx wrangler secret delete ONESEND_SETUP_CODE. Database tables are created on the first request.
To receive mail into the inbox, see Receiving mail with Email Routing. To send real email, connect a provider under Sending providers (Resend, Brevo, Amazon SES, Postmark, Mailgun, Cloudflare Email and others). Until you do, the built-in Sandbox provider accepts email and does not deliver it.
What npm run cf:setup does
cf:setup runs node apps/worker-cf/scripts/cf.mjs setup. Add -- --dry-run to print the commands without running them. It does the following:
- Checks
wrangler whoami. - Creates a D1 database:
wrangler d1 create onesend. If a database with that name exists, it is reused.--location weur(oreeur,apac,oc,wnam,enam) sets the location hint. - Creates a queue:
wrangler queues create onesend-jobs. If this fails, setup continues without a queue, and the Cron Trigger runs jobs instead.--no-queueskips this step. - Creates an R2 bucket:
wrangler r2 bucket create onesend-files. It adds a lifecycle rule that expiresattachments/objects after the retention period plus 30 days (--retention-days 90sets the retention period). If this fails, setup continues without R2.--no-r2skips this step. - Asks for the public URL, then writes
apps/worker-cf/wrangler.jsoncfromwrangler.jsonc.examplewith your ids. It also writesapps/worker-cf/.dev.vars, which holds a separate secret for local development only. - Generates
ONESEND_SECRETand stores it withwrangler secret put ONESEND_SECRET. The value is printed once: save it in a password manager. Provider credentials and webhook secrets are encrypted with it, and they cannot be read without it. - Generates a one-time setup code (
XXXX-XXXX-XXXX), stores it withwrangler secret put ONESEND_SETUP_CODEand prints it. The sign-up page asks for it when you create the owner account.
Other options: --name, --db, --queue, --bucket, --public-url, --yes (no prompts) and --force (write wrangler.jsonc again).
wrangler.jsonc is not committed. It holds account-specific values such as the D1 id and resource names. These are not secrets, but they belong to one deployment, so .gitignore excludes wrangler.jsonc. The committed template is apps/worker-cf/wrangler.jsonc.example. To keep your deployment's configuration in a private fork, remove the line from .gitignore. It never holds secrets.
Doing it by hand
cd apps/worker-cf
npx wrangler d1 create onesend # copy the database_id
npx wrangler queues create onesend-jobs
npx wrangler r2 bucket create onesend-files
cp wrangler.jsonc.example wrangler.jsonc # paste the database_id, set ONESEND_PUBLIC_URL
openssl rand -base64 32 # keep this value safe
npx wrangler secret put ONESEND_SECRET # paste it
cd ../.. && npm run cf:deploy
Configuration
Settings that are not secret go in "vars" in wrangler.jsonc. Secrets go in with npx wrangler secret put <NAME> (run it in apps/worker-cf). All the settings in self-hosting.md work as environment variables, except the ones listed under What is not available.
| Name | Kind | |
|---|---|---|
ONESEND_SECRET | secret, required | Master secret (32 characters or more). Without it, the Worker answers every request with a 503 that tells you how to set it. |
ONESEND_PUBLIC_URL | var | The base URL used in tracking links, unsubscribe links and provider webhooks. Set it to your custom domain or workers.dev URL. If it is not set, the first request's origin is used and a warning is logged. |
NODE_ENV | var | production (the default on Workers). |
ONESEND_SIGNUP | var | first-user (default), open, invite or closed. closed needs a request from the same machine to create the owner, which never happens on Workers, so do not use it before the owner exists. |
ONESEND_RETENTION_DAYS, LOG_LEVEL, ONESEND_CORS_ORIGINS, … | var | As on Node. |
ONESEND_WORKER_CONCURRENCY | var | Jobs claimed at once per drain. The Workers default is 4 (8 on Node), so a drain stays within D1's per-invocation query limit. |
ONESEND_RATE_LIMITER | var | database by default on Workers: sign-in, sign-up, form and conversion limits are counted in D1 (the rate_limits table, one write per check), shared by every isolate. memory counts per isolate. |
ONESEND_DRAIN_AFTER_RESPONSE | var | Without a Queue: off stops running due jobs right after a response, so jobs run only on the Cron Trigger. |
<NAME>_FILE settings do not work on Workers, because there is no filesystem; the Worker answers with a configuration error. DATABASE_URL is refused as well, because the only database on Workers is D1.
compatibility_date is pinned in the example (2026-10-15) together with nodejs_compat. Change it on purpose, and run the tests when you do.
Deploy
npm run cf:deploy
This builds the dashboard (npm run build:web) and the snapshot of the bundled starter templates (npm run cf:gallery), which the Worker serves when the hosted template gallery cannot be reached. It then prints a D1 Time Travel restore point (see Backups) and runs wrangler deploy. Arguments after -- are passed to wrangler deploy.
Logs: cd apps/worker-cf && npx wrangler tail, or Workers → onesend → Logs in the dashboard (observability is turned on in the example).
On Workers Paid, you can allow long campaign batches and imports more CPU time by uncommenting "limits": { "cpu_ms": 300000 } in wrangler.jsonc.
Custom domain
The domain's DNS must be on Cloudflare. Either:
- In the dashboard, go to Workers → onesend → Settings → Domains & Routes → Add → Custom domain, and enter
mail.example.com. Or - Add
"routes": [{ "pattern": "mail.example.com", "custom_domain": true }]towrangler.jsoncand deploy.
Then set "ONESEND_PUBLIC_URL": "https://mail.example.com" and deploy again. Links in email you have already sent keep the old URL, so set the domain before you send real mail. Provider webhooks registered while the URL was a workers.dev address still point there: open each sending provider and save it again, or rotate its webhook URL.
Receiving mail with Email Routing
The Worker has an email() handler, so one deployment both sends and receives. No other Worker is needed (the standalone Email Worker is for a Node server; see Receiving mail).
- In OneSend, add the domain under Senders & domains with inbound mail set to Cloudflare Email Routing, and publish the ownership TXT record so the domain verifies. Then create a mailbox under Inbox → Addresses: an address, a catch-all
*, or plus addressing. - In the Cloudflare dashboard, go to your domain → Email → Email Routing → Get started. Cloudflare adds its MX and SPF records.
- Under Routing rules, create a custom address (for example
support@) or turn on the catch-all, with the action Send to a Worker →onesend.
Messages are parsed, threaded, filtered by your inbox rules and the spam filter, and stored directly, with no HTTP hop. The SPF/DKIM/DMARC verdict comes from Cloudflare's own ARC-Authentication-Results (authserv-id mx.cloudflare.net, override with AUTHSERV_ID). An Authentication-Results header written by the sender is never trusted.
FORWARD_TO="you@example.com"also forwards every message to verified Email Routing destination addresses. Copies are forwarded even when storing the message fails.REJECT_UNKNOWN="true"rejects mail for addresses that no workspace receives. By default such mail is accepted and dropped, with a warning in the logs.REJECT_ON_FAILURE="true"makes Cloudflare reject the message when it cannot be stored (and nothing is forwarded), so the sender gets a bounce.- Email Routing accepts messages up to 25 MiB.
- Without an active license key the workspace is locked, and mail is still received and stored (see Without a license key).
The workspace on Workers
The inbox, calendar, booking pages and drive run in the same Worker, on D1. What they need, and what Workers cannot do:
- R2 (
FILES) for the drive and for mail import uploads: without it they answer 503drive_storage_unavailableandimport_storage_unavailable. Large received and sent attachments go there too.cf:setupcreates the bucket; its lifecycle rule only expiresattachments/, so drive files (drive/) and import chunks are kept until the drive or the import deletes them. - Queues and the Cron Trigger run the workspace's jobs like the others: reminders and the inbox sweep every minute on the cron, invitations by email, large imports and drive deletions in slices within the per-invocation query budget.
ONESEND_PUBLIC_URLmust be the public address: booking pages (/book/<handle>), drive links (/share/<token>), the calendar feed and invitation answers use it.- Not on Workers: the IMAP and POP servers for mail apps, SMTP submission and the built-in SMTP receiver (no listening sockets), and connected IMAP accounts (no raw TCP from the sync jobs). Gmail, Microsoft and Zoho accounts work (HTTPS APIs), synced by the periodic accounts job (there is no IMAP IDLE on Workers). To offer mail apps or IMAP accounts, run the Node edition.
- Limits that matter: a D1 database holds at most 10 GB, so keep mail retention and Trash and Spam retention reasonable; drive files live in R2, not D1. Large mail imports and drive deletions continue across invocations, so they take longer than on Node.
How jobs run
The jobs table in D1 is still the source of truth. Claims, retries with backoff, scheduled sends and dead jobs work exactly as on Node, with the same handlers. Only the polling loop is replaced:
- With the
JOBSQueue: each request or job that stores work that is due soon sends one small "wake" message when it finishes. A request that queues 100 emails sends one message, not 100. A job due later (a retry, a scheduled send within the next 15 minutes) gets a message delayed until it is due. The consumer runs due jobs for up to 25 seconds or 600 D1 queries, then wakes itself again if work is left. - Without a Queue: a request that stores work due now runs it right after the response (
ctx.waitUntil). Everything else runs on the next Cron Trigger, within a minute. - Cron Trigger (
* * * * *, keep it): makes sure the periodic jobs are scheduled and runs anything due. If a wake message is lost, the job runs at the next minute at the latest. A Cron Trigger that runs every minute is within the 5 Cron Triggers allowed on Free and 250 on Paid.
Attachments and R2
D1 limits a row to 2 MB, and attachments are stored base64 encoded, so a 1.5 MB attachment is already close to the limit. With FILES bound, any attachment over about 24 KB (outgoing or received) is stored in R2 under attachments/…. The database row keeps only a reference, and the content is read back when the message is sent, forwarded or resent. Without FILES, attachments stay in the rows, as on Node, and an attachment that pushes a row over 2 MB is refused by D1.
Workspace data exports (see Privacy) are written to the same bucket under exports/ through a multipart upload, and deleted after 7 days. Without FILES, data export answers 503 export_storage_unavailable.
Retention deletes rows in bulk, not the R2 objects. The lifecycle rule that cf:setup adds expires them. To add the rule by hand: npx wrangler r2 bucket lifecycle add onesend-files onesend-attachments attachments/ --expire-days 120.
Migrations and upgrading
Migrations run automatically. The first request (or cron or queue invocation) of each new Worker instance runs the same idempotent migrations as the Node server (CREATE … IF NOT EXISTS, guarded column additions). Applied migrations are recorded in _onesend_migrations. Several instances that start at the same moment are safe. This is the same code path the Node server and the test suite use. A second migration system (wrangler d1 migrations) would have to be kept in step with it, so it is not used.
To upgrade from a download (the self-hosted license): download the new release with your license key on the website's self-host page, unpack it next to the old folder, and copy apps/worker-cf/wrangler.jsonc across (it holds your D1 id and settings; the secrets stay in Cloudflare):
tar -xzf onesend-selfhost-<new>.tar.gz
cp onesend-selfhost-<old>/apps/worker-cf/wrangler.jsonc onesend-selfhost-<new>/apps/worker-cf/
cd onesend-selfhost-<new> && npm install
npm run cf:deploy # prints a Time Travel restore point first, then deploys
From a clone of the repository: git pull && npm install, then npm run cf:deploy.
The new version migrates D1 on its first request. If something goes wrong, roll back the code with npx wrangler rollback (in apps/worker-cf), and roll back the data with the restore point that was printed. Restoring the data also removes everything written since that point.
Upgrading from OneSend
OneSend was called OneSend before. On Workers:
- Vars and secrets.
OPENEMAIL_*vars and secrets are not read any more. A Worker that has one without itsONESEND_*name refuses to start (the error lists each one with its new name); once the new name is set too, it starts and logs a warning about the old one. So, in this order: add the new names (inwrangler.jsonc"vars", and each secret withnpx wrangler secret put ONESEND_SECRETand the others, with the same values), deploy, then delete the old ones withnpx wrangler secret delete OPENEMAIL_…and remove them from"vars". Bindings (D1, R2, queues) are not settings and keep their names. - The inbound Email Worker (Cloudflare Email Routing to
/ingest/cloudflare), deployed on its own, keeps running after the server upgrade. A worker from before the rename sendsX-OpenEmail-Ingest-Secret,X-OpenEmail-Envelope-Toand the otherX-OpenEmail-*headers; the server accepts them until 2027-03-01, so no mail is lost meanwhile. Redeploy it, and rename itsOPENEMAIL_URLandOPENEMAIL_INGEST_SECRETtoONESEND_URLandONESEND_INGEST_SECRET(the new worker reads the old names with a warning until then). - Domain ownership stays verified with the old
_openemail-verifyTXT record until 2027-03-01; publish_onesend-verify(shown on the domain page) before then. Webhooks carry both theX-OneSend-*and theX-OpenEmail-*signature headers until then. See Upgrading from OneSend.
Backups
- D1 Time Travel is always on: 30 days of point-in-time restore on Workers Paid (7 on Free).
npx wrangler d1 time-travel info onesendshows the current bookmark.npx wrangler d1 time-travel restore onesend --timestamp=2026-11-08T10:00:00Zrestores to a point in time, or use--bookmark=<bookmark>.
- Export a copy to keep elsewhere:
npx wrangler d1 export onesend --remote --output=onesend-backup.sql. - R2 has no built-in point-in-time restore. Attachment objects are written once and never changed, so copy the bucket if you need a separate backup.
ONESEND_SECRET: keep a copy. A restored database cannot be decrypted with a different secret.
Local development
npm run cf:dev # wrangler dev on http://localhost:8787 with local D1, Queue and R2
The first time, this writes a local-only wrangler.jsonc (placeholder ids, NODE_ENV=development) and .dev.vars (a local secret), then builds the dashboard and the gallery snapshot. Local data lives in apps/worker-cf/.wrangler/state. npm run cf:deploy refuses a configuration that still has the placeholder ids, so run npm run cf:setup -- --force before deploying.
To run the cron by hand: curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*". To deliver a test email to the email() handler: curl -X POST "http://localhost:8787/cdn-cgi/handler/email?from=a@example.org&to=support@acme.dev" --data-binary @message.eml. Locally, a domain can only verify with development DNS overrides (--var 'ONESEND_DNS_OVERRIDES:{"acme.test":"*"}').
Limits
| Limit | Value (Workers Paid) | What it means for OneSend |
|---|---|---|
| D1 database size | 10 GB, cannot be raised | Keep ONESEND_RETENTION_DAYS reasonable. Campaign bodies are not kept after delivery (they are rebuilt on view). With more data than this, use PostgreSQL on the Node edition. |
| D1 row size | 2 MB | Bind R2 (FILES) for attachments. |
| D1 queries per invocation | 1,000 | Drains stop at 600 queries and continue in a new invocation. Campaign batches read 60 recipients at a time on D1 (200 on Node). Very large campaign starts or CSV imports in one job can still reach the limit. See Known gaps. |
| D1 bound parameters per query | 100 | Handled by the data layer (batch inserts are split). |
| CPU per invocation | 30 s by default, 5 min maximum | Raise it with limits.cpu_ms for large imports and campaigns. |
| Request body | 100 MB (Free and Pro zones), 200 MB (Business) | The server's own limits are lower: 30 MB for raw MIME, 50 MB for a CSV upload. |
| Worker bundle | 10 MB after compression (3 MB on Free), 64 MB before | The Worker is about 9 MB before compression and about 2.3 MB after. |
| Static assets | 20,000 files (Free) / 100,000 (Paid), 25 MiB per file | The dashboard is about 260 files, the largest under 1 MB. |
| Email Routing message size | 25 MiB | Larger messages are rejected by Cloudflare. |
| Queue message delay | up to 24 hours | Only delays of up to 15 minutes are sent; the cron handles anything later. |
Rate limits for sign-in, sign-up, forms and conversions are counted in D1 (ONESEND_RATE_LIMITER=database, the Workers default), so every isolate shares them. They use fixed windows, so up to twice a limit can pass around a window boundary. A Cloudflare WAF rate-limiting rule for /v1/auth/* still adds protection at the edge, before a request reaches the Worker.
What is not available on the Cloudflare edition
| Feature | On Workers | Instead |
|---|---|---|
| SMTP as a sending provider (Gmail, Zoho, Outlook, your own server) | Refused with not_available_on_cloudflare. In the dashboard the provider is labelled "Not available on the Cloudflare edition". Email routed to an existing SMTP connection moves on to the next provider, and the connection shows the reason. | Any HTTP API provider (Resend, Brevo, SES, Postmark, Mailgun, Cloudflare Email, …), or the Node edition. Cloudflare's connect() sockets were not used, because nodemailer needs full Node net/tls with STARTTLS upgrades, and that does not work reliably on Workers. |
| SMTP submission (sending through OneSend with an SMTP client) | Off. The workspace shows no SMTP port. | The HTTP API, SDKs and compatibility endpoints (/compat/resend, /compat/sendgrid, /compat/postmark). |
| Built-in SMTP receiver | Off | Email Routing → email() handler (Receiving mail). |
| IMAP / POP3 access to mailboxes (mail apps) | Off (needs listening sockets) | The dashboard, the API and MCP, or the Node edition. |
| Connected IMAP accounts | Off (no raw TCP from sync jobs) | Gmail, Microsoft and Zoho accounts (HTTPS APIs) work; IMAP accounts need the Node edition. |
| PostgreSQL, SQLite files, PGlite, libSQL/Turso | Refused at startup | D1 only. |
Filesystem settings (*_FILE, onesend.config.json, .env, ONESEND_TEMPLATES_DIR) | Not read | Use vars and secrets. The starter templates are bundled at build time (npm run cf:gallery); the gallery itself is read from ONESEND_GALLERY_URL like on Node (Templates). |
npm run setup, npm run doctor, npm run db:copy | Node only | npm run cf:setup. Moving an existing Node instance's data into D1 is not supported: start the Cloudflare edition with its own database. |
Known gaps
- On D1, a single campaign start or CSV import job uses about 0.3 queries per recipient or row. Starting a campaign to more than roughly 3,500 recipients, or importing a very large file before the import's time budget hands over, can reach the 1,000-query limit of one invocation; the job is then retried.
- Moving an existing Node instance's data into D1 is not supported.
How it is tested
npm test -w @onesend/worker-cf:
suite-*.test.tsrun the server's own API, marketing (campaigns) and inbox test suites against the Worker-built app: the fake D1 binding, the Workers settings, and requests through the Worker'sfetch()handler. Each suite runs twice: once with jobs through thequeue()consumer and in-memory Queue and R2, and once through thescheduled()cron tick with no Queue.worker.test.tscovers configuration errors, wake messages, retries, R2 offload, refusing SMTP, the gallery, the dashboard with SPA fallback and CSP, the cron tick, theemail()handler and the D1 query budget.d1-limits.test.tscounts the D1 queries of each import and campaign job.miniflare.test.tsbundles the Worker with Wrangler and runs it on workerd (local D1, Queue, R2 and assets): sign-up, sending through the real Queue consumer, refusing SMTP, the dashboard, the cron trigger and the email handler. SetSKIP_MINIFLARE=1to skip it.