Documentation Preview

Everything you need to
integrate Fancy Waitlist

REST API, Python SDK, CLI, MCP server, and declarative YAML config. One product, every interface you could want. Here's a preview of what's coming.

5 min

Quick start

Client interfaces

30+

API endpoints

Full

YAML config

Documentation

Browse by section

Organized by interface and use case. Every section includes code examples you can copy when the product launches.

Getting Started

Go from zero to a live waitlist in five minutes. Create an account, connect your SMTP, and drop a signup form on your site.

Quick start (5 minutes)
Concepts overview
Lists, subscribers, referrals
Events and config basics

Integration Guides

Step-by-step walkthroughs for adding a signup form (HTML, React, Vue, Next.js), connecting SMTP providers, and setting up your first waitlist end-to-end.

Signup form — HTML, React, Vue, Next.js
SMTP setup — SendGrid, Postmark, SES
First waitlist end-to-end
OAuth provider configuration

signup-form.html

<!-- Drop this anywhere on your site -->
<form action="https://api.fancywaitlist.com/v1/subscribe"
      method="POST" data-fw-list="launch-waitlist">
  <input type="email" name="email"
         placeholder="[email protected]" required />
  <button type="submit">Join the Waitlist</button>
</form>
<script src="https://cdn.fancywaitlist.com/fw.js"
        data-key="fw_pub_abc123" async></script>

CLI Reference

Install with pip, manage everything from the terminal. Push config, query subscribers, send emails, and validate YAML — all scriptable.

Installation — pip install fancy-waitlist
lists, subscribers, send commands
config push / pull / diff / validate
referrals, events commands

terminal

$ pip install fancy-waitlist
$ fancy-waitlist config push fancy-waitlist.yaml
Validating config...
Config valid. Applying changes:
  + list: launch-waitlist
  + referral milestones: 3 tiers
  + event emails: welcome, referral_success
Config applied successfully.
$ fancy-waitlist subscribers --list launch-waitlist
Found 1,247 subscribers
  #12  [email protected]     referrals: 8   tier: insider
  #45  [email protected]        referrals: 5   tier: early-bird
  ...

MCP Server

Connect your waitlist to Claude, Cursor, or any AI tool that supports MCP. Your AI agent gets full access to manage subscribers, send emails, and query stats.

Setup for Claude, Cursor, and others
Available tools (mirrors the API)
Example AI workflows
Natural language waitlist management

claude_desktop_config.json

{
  "mcpServers": {
    "fancy-waitlist": {
      "command": "uvx",
      "args": ["fancy-waitlist-mcp"],
      "env": {
        "FANCY_WAITLIST_API_KEY": "fw_live_abc123"
      }
    }
  }
}

Python Client

A fully typed Python SDK. Install, authenticate, and manage your entire waitlist programmatically — from Jupyter notebooks, scripts, or production services.

Installation and authentication
Full API reference (typed)
Subscriber management examples
Email sending and templates

example.py

from fancy_waitlist import FancyWaitlist
fw = FancyWaitlist(api_key="fw_live_abc123")
# Add a subscriber
sub = fw.subscribers.create(
    email="[email protected]",
    list="launch-waitlist",
    referral_code="ref_x7k9",
)
print(f"Position: #{sub.position}")
# Send an event email
fw.emails.send(
    list="launch-waitlist",
    template="weekly-update",
    subject="What we shipped this week",
)

REST API Reference

Full endpoint documentation with request/response examples, authentication via API keys, error codes, and rate limits.

All endpoints documented
Authentication (API keys)
Error codes and rate limits
Request / response examples

api-example.sh

curl -X POST https://api.fancywaitlist.com/v1/subscribers \
  -H "Authorization: Bearer fw_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "list": "launch-waitlist",
    "referral_code": "ref_x7k9"
  }'
# Response 201 Created
{
  "id": "sub_8fj2k",
  "email": "[email protected]",
  "position": 1248,
  "referral_link": "https://wl.io/ref_m3p1",
  "milestone": null
}

Config File Reference

The complete YAML schema for fancy-waitlist.yaml. Define lists, referrals, email templates, SMTP, fraud prevention, and graduation rules — all declaratively.

Complete YAML schema
Common setup examples
Environment overrides
Validation and diffing

fancy-waitlist.yaml

# fancy-waitlist.yaml
apiVersion: v1
kind: WaitlistConfig
metadata:
  name: my-product-launch
smtp:
  provider: sendgrid
  from_name: "My Product"
  from_email: [email protected]
lists:
  - name: launch-waitlist
    position_display: relative
    signup:
      email: true
      oauth: { google: true, github: true }
referrals:
  enabled: true
  double_sided: true
  milestones:
    - tier: early-bird
      referrals: 3
      reward: "Priority access"
    - tier: insider
      referrals: 10
      reward: "3 months free"
emails:
  welcome:
    enabled: true
    subject: "You're #{{position}} in line"

Guides

Deep-dive walkthroughs for graduation, referral milestones, event email configuration, and fraud prevention tuning.

Graduation walkthrough
Setting up referral milestones
Configuring event emails
Fraud prevention tuning

Coming Soon

Full docs launch with early access

Join the waitlist to get early access to the full documentation, API keys, and a sandbox environment to start building before everyone else.

Join the Waitlist

Free tier available. No credit card required.

Everything you need tointegrate Fancy Waitlist