Run a waitlist

Use Waitlist sign-up mode to collect interest and invite people when your product is ready. Entries live in your Users directory and retain their IDs when they become active users. You can later switch the same product to public sign-up.

Before you start

• Install Lepsto Users for the product. Existing keys, allowed origins, and libraries continue to work when you change sign-up modes.
• Prepare a form on an allowed origin or a landing page that accepts the widget script.
• Configure a sender address on a verified domain for confirmation and invitation emails.

Turn the waitlist on

1. Open Users → Configuration → Signup and set the sign-up mode to Waitlist. Sign-up now collects waitlist entries instead of creating active accounts. See Configure authentication for all sign-up modes.

2. Choose the confirmation and retention settings:

• Double opt-in: requires email confirmation before a signup counts as confirmed. Find it in Users → Configuration → Waitlist widget, alongside the heading and button label.
• Retention window: automatically removes entries that have not become users after the configured period. Set it through the product API or an agent; the configuration screen has no field for it.

Collect signups

3. Add one or both collection surfaces:

• Custom form: submit the email address through the browser library. Your application controls layout and validation. The form must run on an allowed origin.

• Embeddable widget: add the script and a placeholder to your landing page. It renders a themed form and also detects placeholders added after page load, including on single-page sites.

Both paths enforce rate limits, CAPTCHA by default, and your email-domain restrictions: allowlists or blocklists, disposable-address blocking, and + sub-address rules.

Each entry retains attribution from the referring page and campaign parameters. Consent evidence includes the accepted wording and version, acceptance time, browser, and the visitor’s public IP resolved by the platform. This evidence stays with the entry for its lifetime.

What the signup endpoint answers

The signup endpoint accepts waitlist submissions only in Waitlist mode. Other modes return:

409 {
  "code": "signup_mode_mismatch",
  "message": "This product is not accepting waitlist signups."
}

If you receive this error, check the sign-up mode. It can occur before setup or after launch if an old landing page still submits to the waitlist endpoint. Users → Waitlist also warns when the current mode cannot collect entries.

Rate limits and CAPTCHA run before those checks, using the submitted address regardless of whether it is known. An accepted response is not proof that a new record was created.

What a waitlist record is

A waitlist entry has a stable directory ID, email address, and attached metadata. It has no password, linked login, or session. While access remains gated by the waitlist, sign-in fails like an unknown address until an invitation is accepted.

You can search, inspect, annotate, and export these records as described in User management. Data requests include them too. Waitlisted records are excluded from the default user list.

Watch the funnel

4. Open Users → Waitlist to view counts and entries for each state:

Filter the screen with All, Pending, Invited, Registered, or Withdrawn. The screen shows joining dates but has no date filter. For an agent, users_waitlist_list supports the funnel status and confirmed filter, while users_waitlist_funnel returns counts; both require a product-scoped token with read access. Attribution is stored on each entry, not available as a search filter.

Invite a cohort

5. Select entries on Users → Waitlist and choose Invite selected. You can select individual entries or all eligible entries on the current page. Batches contain at most 100 entries, also the limit for users_waitlist_invite with product-scoped write access. Registered and withdrawn entries cannot be selected.

The invitation email carries a single-use token into your sign-up flow. The recipient sets a credential using an enabled method and completes the applicable authentication requirements. Completion creates an active session and changes the entry to Registered, keeping the original directory ID.

An unaccepted invitation can expire or be revoked. Either returns the entry to Pending without losing attribution, so you can invite it again. Revoke through the product API or an agent; the waitlist screen only sends invitations.

Verify it worked

1. Submit a test address and check for 200 {"status": "accepted"}. Complete double opt-in if enabled.
2. Find the Pending entry in Users → Waitlist and inspect its attribution.
3. Select Invite selected. Confirm the entry becomes Invited and the email arrives.
4. Accept the invitation and finish sign-up. Confirm it becomes Registered with the same user ID.

A 409 signup_mode_mismatch means collection is disabled by the sign-up mode. If an accepted response produces no entry, check for a duplicate, existing user, or suppressed address: the public response deliberately does not distinguish them.

Handle withdrawal and removal

Waitlist emails link to a withdrawal page that requires confirmation. Opening the link alone does not withdraw anyone, protecting against mail scanners. Confirmation marks the entry Withdrawn and suppresses the address. Every waitlist email checks that suppression, including after an attempted re-import.

For full erasure, open the product’s workspace settings and use Data processing → Forget a person. This removes the person’s data, including waitlist consent evidence. The waitlist screen does not perform erasure.

Import a list you already have

For a legacy list, choose Waitlist in Users → Import, or use users_waitlist_import with product-scoped write access. Send at most 500 entries per call. Each entry must include the source consent proof: policyVersion, acceptedAt, and source. Preserve those original values; do not substitute the import time. Attribution and unsafeMetadata can also be carried over. See Migration for the import workflow.

The import sends no email and creates pending entries with unverified addresses. They are confirmed by default; set confirmed: false when the old system never confirmed reachability. Unconfirmed entries are not invited. Re-imports skip duplicates and suppressed addresses, and the per-row report explains failures.

Open the doors

When ready for launch, set Users → Configuration → Signup to Public. Normal sign-up starts creating accounts immediately. The waitlist endpoint now returns signup_mode_mismatch; remove the old widget or direct visitors to your regular sign-up.

Changing the mode does not invite or delete existing entries. Invite them in batches or let them register through public sign-up. A waitlisted address does not block ordinary registration.

Next steps

• Configure authentication for modes, domain restrictions, and CAPTCHA.
• User management for directory records and erasure.
• Migration for importing an existing list.
• Authentication flows for invitation acceptance.