LoginGet started

API Documentation

Integrate waitlists into your application with our simple REST API

Quick Start

Get started with waitlist.email API in 3 simple steps:

  1. Create a waitlist in your dashboard
  2. Get your API key and waitlist ID
  3. Start making API requests to the endpoints below

Authentication

All API requests require authentication using your API key. You can authenticate in two ways:

Method 1: API Key Header (Recommended)

Include your API key in the request headers:

X-Waitlist-Api-Key: your_api_key_here

Method 2: Domain Whitelist

For client-side JavaScript, add your domain to the allowed domains list in your waitlist settings.

Base URL

https://waitlist.email/api

API Endpoints

Create Subscriber

Add a new subscriber to your waitlist

POST/api/subscribers/create

Request Body

{
  "waitlist": "your_waitlist_id",
  "email": "user@example.com",
  "name": "John Doe",           // Optional
  "phone": "+1234567890",       // Optional
  "referredBy": "abc123",       // Optional: referral code
  "metadata": {                 // Optional: Pro plan only
    "source": "landing_page",
    "userId": "user_123"
  }
}

Example Request

curl -X POST https://waitlist.email/api/subscribers/create \
  -H "Content-Type: application/json" \
  -H "X-Waitlist-Api-Key: your_api_key" \
  -d '{
    "waitlist": "your_waitlist_id",
    "email": "user@example.com",
    "name": "John Doe"
  }'

Response

{
  "message": "Subscriber created",
  "subscriber": {
    "id": "clm1234567890",
    "email": "user@example.com",
    "name": "John Doe",
    "referralCode": "abc123",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Retrieve Subscriber

Get subscriber information and waitlist position

POST/api/subscribers/retrieve

Request Body

{
  "waitlist": "your_waitlist_id",
  "email": "user@example.com"
}

Example Request

curl -X POST https://waitlist.email/api/subscribers/retrieve \
  -H "Content-Type: application/json" \
  -H "X-Waitlist-Api-Key: your_api_key" \
  -d '{
    "waitlist": "your_waitlist_id",
    "email": "user@example.com"
  }'

Response

{
  "message": "Subscriber retrieved",
  "subscriber": {
    "id": "clm1234567890",
    "email": "user@example.com",
    "name": "John Doe",
    "referralCode": "abc123",
    "referralCount": 3,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Delete Subscriber

Remove a subscriber from your waitlist

POST/api/subscribers/delete

Request Body

{
  "waitlist": "your_waitlist_id",
  "email": "user@example.com"
}

Example Request

curl -X POST https://waitlist.email/api/subscribers/delete \
  -H "Content-Type: application/json" \
  -H "X-Waitlist-Api-Key: your_api_key" \
  -d '{
    "waitlist": "your_waitlist_id",
    "email": "user@example.com"
  }'

Response

{
  "message": "Subscriber deleted"
}

Error Handling

All API responses use standard HTTP status codes. Errors return JSON with a descriptive message:

400 Bad Request

{
  "message": "Email is required"
}

403 Forbidden

{
  "message": "This feature requires a Pro subscription. Please upgrade to continue."
}

404 Not Found

{
  "message": "Waitlist not found"
}

SDKs & Libraries

While our API is simple enough to use with standard HTTP requests, here are some popular libraries for different platforms:

JavaScript/TypeScript

// Using fetch (built-in)
fetch('https://waitlist.email/api/subscribers/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Waitlist-Api-Key': 'your_key'
  },
  body: JSON.stringify({
    waitlist: 'your_waitlist_id',
    email: 'user@example.com'
  })
})

Python

import requests

response = requests.post(
  'https://waitlist.email/api/subscribers/create',
  json={
    'waitlist': 'your_waitlist_id',
    'email': 'user@example.com'
  },
  headers={
    'X-Waitlist-Api-Key': 'your_key'
  }
)

Need Help?

Check out our integration examples in your dashboard or contact support

View DashboardContact Support