Build a waiting list with double opt-in on your own Cloudflare account
By Flavio
Updated
Run Waiting Lists locally, post an address to a list, confirm it from the saved email, export it with the CLI, then deploy the same code to your Cloudflare account.
Waiting Lists collects email addresses from a form you already have, sends a confirmation email, and only counts an address once the person presses a button on the confirmation page. You deploy it to your own Cloudflare account, so the Worker and the D1 database with every address in it are yours. The form on waitinglists.dev runs on this same code.
The nice part is that the whole double opt-in flow works on your Mac before you deploy anything. Locally, the confirmation email is saved as a file instead of being sent, so you can read it and follow the link. We’ll do that first, then deploy.
Two posts cover the design behind it: scanner-safe double opt-in explains why opening the link doesn’t confirm, and idempotent double opt-in signup explains why a second submit doesn’t send a second email.
Run it locally
You need Node.js 22.12 or newer. Unzip the source from your Polar receipt, then install and run the checks:
npm ci
npm run check
npm test
Test Files 9 passed (9)
Tests 38 passed (38)
Copy the settings template:
cp .dev.vars.example .dev.vars
Fill in every value. ADMIN_PASSWORD_HASH is the lowercase SHA-256 of your admin password:
printf %s 'your-long-admin-password' | openssl dgst -sha256
SESSION_SECRET and SUBSCRIBER_TOKEN_SECRET must be two different random values of at least 32 bytes. openssl rand -hex 32 gives you one each time you run it. The login page uses Turnstile, so add the site key and secret of a Turnstile widget you own. Keep .dev.vars out of Git.
Create the local D1 database and start the dev server:
npm run db:migrate:local
npm run dev
The migrations print a table with six files, 0001_initial.sql to 0006_global_settings.sql. The app runs at http://localhost:4321. Sign in at /login with the username and password from .dev.vars.
Create a list
In the dashboard, click + New list. A list has a name, an endpoint slug, and the website origins allowed to post to it:

An origin is the scheme, the hostname, and the port if there is one. https://hostingpicker.dev and https://www.hostingpicker.dev are two different origins, so add both if people reach your site both ways. Separate them with commas. * accepts any site.
For this walkthrough I made a list called Hosting Picker, slug hosting-picker, with both of those origins.
The first migration also creates a list called waitinglists.dev with * as its origin. It’s the one the waitinglists.dev site uses. On your install, delete it or change its origins, because it accepts posts from anywhere.
Post an address
The endpoint takes exactly two fields, email and consent. Let’s call it with curl, setting the Origin header a browser would send from the site:
curl -i -X POST http://localhost:4321/api/subscribe/hosting-picker \
-H 'Origin: https://hostingpicker.dev' \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","consent":true}'
HTTP/1.1 202 Accepted
access-control-allow-origin: https://hostingpicker.dev
cache-control: no-store
content-type: application/json
{"ok":true,"message":"Thanks — you’re on the waitlist. Check your inbox if a confirmation step is needed."}
Running the same command again returns the same 202 and the same message, and no second email is sent. The response never tells you whether the address was new, pending or already confirmed.
These are the other answers I got from the same endpoint:
| Request | Status | Message |
|---|---|---|
Extra field, {"email":…,"consent":true,"name":"Flavio"} | 400 | Enter a valid email and agree to join the waitlist. |
"consent": false | 400 | Enter a valid email and agree to join the waitlist. |
| Broken JSON | 400 | Send a valid email and explicit consent. |
Origin: https://flaviocopes.com, not in the list | 403 | This website is not allowed to submit to this list. |
Slug hostingpicker instead of hosting-picker | 404 | Waiting list not found. |
| Sixth request in a minute | 429 | Too many attempts. Please try again in a minute. |
The rate limit is 5 requests per 60 seconds per IP and list, set by SUBSCRIBE_RATE_LIMIT in wrangler.jsonc. Requests with a bad body count toward it. Wrong-origin and wrong-slug requests are refused before it, so they don’t. There’s a second limit per email address. A 503 means the database or the email submission failed.
A request with no Origin header is accepted, and anyone can send a fake one from a script. The origin list stops other websites from using your form in the browser. Against scripts, the endpoint relies on the rate limits and on double opt-in.
Confirm it from the saved email
The dev server log shows the email instead of sending it:
send_email binding called with MessageBuilder:
From: "waitinglists.dev" <[email protected]>
To: [email protected]
Subject: Confirm your place on Hosting Picker
Below that it prints the path of a .txt and an .html copy, saved under .wrangler/tmp/email/ in the project folder. The text one holds the confirmation link, valid for 24 hours, and a removal link:
Confirm your place on Hosting Picker
Someone asked to add this email address to Hosting Picker. Review and confirm here:
http://localhost:4321/confirm?token=DgAL7gueaaYKiaWf2QaT63VGt7UlplG4VD5gYezRx8Q
This link expires in 24 hours. If you did not make this request, ignore this message or remove the request here:
http://localhost:4321/remove?subscriber=0ce52a05-2383-4fef-add9-a10d4532c3cc&signature=df76cb08797de67dc509a0ceadd8b85a662847800b445f608e5f602173f50a71
Open the confirmation link. The page says Confirm your email. with a Confirm my place button, and the subscriber is still pending in the database. That’s what an email scanner sees when it follows the link, and it changes nothing.
Press the button. It sends a POST with the token, the page changes to You’re on the list., and the row becomes confirmed with a confirmed_at time. Pressing it again, or reloading the POST, shows This link is invalid or expired., because the token works once.
Pending addresses are deleted once their link expires. Confirmed ones are deleted 24 months after confirmation, by the daily cron in wrangler.jsonc (17 2 * * *). If you change that period, change the privacy notice too.
Put the form on your site
The list page in the dashboard has a Form setup tab with ready-to-copy HTML and JavaScript. The CLI prints the same HTML, which we’ll set up next:
<form method="post" action="http://localhost:4321/api/subscribe/hosting-picker">
<input type="email" name="email" required />
<label>
<input type="checkbox" name="consent" value="yes" required />
I want updates about this waitlist and agree to the privacy notice.
</label>
<button>Join the waitlist</button>
</form>
Add a <label> for the email field and link your privacy notice in the consent text. Don’t add any other named field, a hidden input or a Turnstile token included, because the endpoint rejects a body with more than email and consent. The consent value can be yes, on, 1 or true.
A plain form posts and shows the JSON answer as a new page. To keep people on your page, use the JavaScript version from Form setup. The endpoint also returns plain text instead of JSON when the request has an HX-Request: true header, for htmx forms. If your site already has a form, connect a plain HTML form to your waiting list endpoint covers the changes and the origin and extra-field errors.
Export with the CLI
The CLI talks to /api/v1 with an API key. Create one at /admin/agent (the Agent access button in the dashboard). It’s shown once. On a Mac, pipe it from the clipboard so it doesn’t end up in your shell history:
pbpaste | npm run waitinglists -- configure --key-stdin
It saves the key in ~/.config/waitinglists/credentials.json, readable only by you. Without --api-url it uses http://localhost:4321/api/v1. For the deployed service, add --api-url https://<your host>/api/v1.
List the lists:
npm run waitinglists -- lists
11111111-2222-4333-8444-555555555555 Hosting Picker 1 confirmed http://localhost:4321/api/subscribe/hosting-picker
e7f1fca0-40cc-4c0b-9fc0-4dc21bb0b532 waitinglists.dev 0 confirmed http://localhost:4321/api/subscribe/waitinglists-dev
Then export. The ID comes first. You can leave it out in a folder linked with waitinglists init, which creates a list and writes .waitinglists.json:
npm run waitinglists -- export 11111111-2222-4333-8444-555555555555 --format universal --output hosting-picker.csv
It prints Export saved to followed by the full path of the file. Only confirmed addresses are exported. These are the five formats, with the size of each file for my one confirmed address:
--format | Columns | Size |
|---|---|---|
archive (default) | email,country,confirmed_at,consent_at,consent_version | 172 bytes |
universal | email | 33 bytes |
sendy | Name,Email | 41 bytes |
kit | Email address | 41 bytes |
mailchimp | Email Address,OPTIN_TIME,CONFIRM_TIME | 109 bytes |
archive is the consent record, the one to keep. My row had replace-with-your-consent-version in its last column, because I never changed CONSENT_VERSION in wrangler.jsonc. Set it before you collect real addresses.
The files are created with -rw------- permissions. Exporting again to the same file name fails with waitinglists: EEXIST: file already exists, so pick a new name or delete the old file. The CLI never prints subscriber data to the terminal.
Without an ID in a folder that isn’t linked, you get:
waitinglists: No list ID supplied and this directory is not linked. Run `waitinglists init`.
Deploy to your Cloudflare account
In your account, create a D1 database, a Queue, a Turnstile widget for your hostname, and an Email Service sender on a domain you control. Then replace the placeholders in wrangler.jsonc:
APP_URL, the HTTPS address of the service, used in every email linkEMAIL_FROMandallowed_sender_addresses, both set to your onboarded senderCONSENT_VERSION,TURNSTILE_SITE_KEYandTURNSTILE_HOSTNAMESdatabase_idof your D1 database, and the queue name
The emails and pages still say waitinglists.dev, and /privacy has sample contact details. Change both before real people sign up.
The five secrets go in with wrangler secret put, not in vars:
npx wrangler secret put ADMIN_USERNAME
npx wrangler secret put ADMIN_PASSWORD_HASH
npx wrangler secret put SESSION_SECRET
npx wrangler secret put SUBSCRIBER_TOKEN_SECRET
npx wrangler secret put TURNSTILE_SECRET
Apply the migrations to the remote database and deploy:
npm run db:migrate:remote
npm run deploy
Then repeat the test from your real site: submit an address you own, open the email, press the button, export. The list page shows each confirmation email’s delivery state (delivered, deferred, bounced, rejected or failed), and every pending address has a Resend confirmation link that sends a fresh one. If nothing arrives, look at that state and at EMAIL_FROM first. Sending email from a Worker is covered in How to send email with Cloudflare Email Service.
The D1 database holds the same addresses as your exports, so take a backup before you run a new migration.
Get Waiting Lists
Collect confirmed subscribers with your own forms, dashboard and agent CLI on your Cloudflare account.
See Waiting Lists → · Read the docs · $20. See the app page for tax details, with full source code.
Want me to talk about your product? You can sponsor this site.