Adding a waitlist to your app: four ways to wire it up, and what breaks the first signup

I make Waitlister, a waitlist tool, so the examples here use it. The shape carries over to most tools.

The signup part of a waitlist is small. The decision that matters is where the signup lives, because that decides how much code you write and what can go wrong on your first test.

The four options

Option	Code	Good for
Hosted page	none	no site yet, or you want something live today
Embedded form	a snippet or plugin	an existing Framer, Webflow, WordPress or Shopify site
Your own HTML form	one form tag	full control over markup and styling
API or SDK	a few lines	signup inside your app, or a custom flow

If your site already gets traffic, put the signup there. If the site doesn't exist yet, a hosted page gets you live fastest. The last two are the ones that involve code.

Your own HTML form

Any form can post straight to the waitlist:

<form action="https://waitlister.me/s/YOUR_WAITLIST_KEY" method="POST">
  <input type="email" name="email" required placeholder="[e-mail]" />
  <button type="submit">Join the waitlist</button>
</form>

On submit, the subscriber is redirected to a hosted thank-you page with their queue position and a referral link, so you don't have to build one.

Before you test it, add your site's domain to the waitlist's whitelisted domains (waitlist → Settings). Until you do, the endpoint rejects submissions from that site with a 403.

Waitlister's CAPTCHA doesn't cover a form you built yourself, so bot protection on this route is yours to handle.

The API or SDK

npm install waitlister

import { Waitlister } from 'waitlister'

// Server-side only: the key must not reach the browser
const wl = new Waitlister({ accountKey: 'wl_acct_…', waitlistKey: 'YOUR_WAITLIST_KEY' })
const result = await wl.signUp({ email: '[e-mail]' })
// result.position, result.referral_code, result.redirect_url

There are two kinds of key, and the difference matters:

• Account API keys (wl_acct_…, Settings → API keys) work on every plan, including free, with lower rate limits on the smaller plans. One key covers every waitlist you own, and it can also create waitlists (up to your plan's waitlist limit), which is handy in setup scripts and agent workflows.
• Per-waitlist keys (passed as apiKey) need the Growth plan, and so does reading or changing subscriber records over the API.

On a plan without access, the SDK throws a typed PlanError instead of failing silently. If you'd rather not handle a key at all, signUpViaForm from the same package posts to the public form endpoint and gives you the hosted thank-you page URL to redirect to. The full schema is in the OpenAPI spec.

What breaks the first test signup

1. The domain isn't whitelisted (HTML form route): submissions return 403 until it is.
2. You tested with a fake address. Waitlister validates deliverability at signup, so [e-mail] is rejected. Use a real address you control.
3. You re-tested with the same address. Signing up again with an address that's already on the list doesn't create a new signup, so no welcome email goes out. Delete the first signup on the Submissions page, or use a different address (a +alias works).

The part that isn't code

Getting the signup, thank-you page and welcome email working fits in an afternoon. Whether the list turns into customers depends on two things no SDK handles.

The first is where visitors come from. Subscribers = visitors × the share who sign up, so if you want 300 people and one visitor in five signs up, you need 1,500 visitors. (That rate is made up for the arithmetic; use your own once you have some traffic.) Plan where those visitors will come from before you polish the page.

The second is what you send people while they wait. Set up the welcome email before any traffic arrives and send a short update every week or two, or the list tends to go cold before launch day.

I wrote up the whole process, including the welcome email I'd use and how to protect the list from fake signups, here: How to create a waitlist, step by step.