Waitlist API reference

Waitlist API · Waitlist-Settings

put/v1/workspaces/{workspace_id}/waitlist/settingsAuth

Update workspace-level Waitlist defaults

Only the fields you send change. Returns the settings with the email setup state, like the read.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Request body

default_sender_domain_idstring · uuid

Mail domain UUID to use as default sender for Waitlist notifications. null clears the override.

Example: "5e1f3a2b-8c4d-4e6f-9a0b-1c2d3e4f5a6b"

default_heimdall_app_slugstring

Auth consumer-app slug to invite approved entries into. null clears the link.

Example: "acme-product"

brand_namestring

Brand name returned in the public waitlist payload. Customer frontends render it on their own signup form.

Example: "Acme"

brand_logo_urlstring · uri

Logo URL returned in the public waitlist payload. Customer frontends render it on their own signup form.

Example: "https://acme.com/logo.png"

primary_colorstring

Primary brand colour as #RRGGBB

Example: "#4F46E5"

notifications_via_envoiboolean

Route Waitlist notifications through the Mail service instead of staying silent. Needs a sender (the workspace default in `workspace` mode, or the custom domain + address) and a template for every event. Turning it on (from off) creates the default templates `waitlist-welcome`, `waitlist-approved` and `waitlist-rejected` in Mail for every empty slot, reusing a template that already has that name, with your own Mail access. Default false; when off, Waitlist sends no notification emails and the customer is expected to handle email via the webhook lane.

Example: true

sender_modeobject

Where the From comes from. `workspace` (the default): the workspace default sender set in Mail, resolved at send time, so changing it in Mail changes it for every product. `custom`: `default_sender_domain_id` + `default_sender_address`. Sending `default_sender_address` without `sender_mode` sets `custom`; sending it as null sets `workspace`.

Example: "workspace"

default_sender_addressstring · email

The From used when `sender_mode` is `custom` (kept, but unused, in `workspace` mode). Must belong to default_sender_domain_id. null clears it.

Example: "hello@mail.acme.com"

welcome_template_namestring

Mail template name used for entry.created notifications. Must already exist in the workspace template store.

Example: "waitlist-welcome"

approved_template_namestring

Mail template name used for entry.approved notifications. Must already exist in the workspace template store.

Example: "waitlist-approved"

rejected_template_namestring

Mail template name used for entry.rejected notifications. Must already exist in the workspace template store.

Example: "waitlist-rejected"

Response · 200 Updated workspace Waitlist settings with the email setup state.

workspace_id*string · uuid

The workspace.

default_sender_domain_id*string · uuid

Mail domain UUID used as default sender for Waitlist notifications.

default_heimdall_app_slug*string

Auth consumer-app slug approved entries are invited into.

brand_name*string

Brand name for Waitlist emails and the public info; null when unset.

brand_logo_url*string

Logo URL for Waitlist emails and the public info; null when unset.

primary_color*string

Primary brand colour as #RRGGBB

notifications_via_envoi*boolean

Whether Waitlist notifications are routed through the Mail service.

sender_mode*object

Where the From comes from: `workspace` (the workspace default sender set in Mail; the default) or `custom` (`default_sender_domain_id` + `default_sender_address`). Workspaces that had an address before this setting existed are `custom`.

Example: "workspace"

effective_sender*object

The sender Waitlist emails actually go out from, with its live status in Mail.

default_sender_address*string

The From used when `sender_mode` is `custom`.

welcome_template_name*string

Mail template sent on sign-up; null when unset.

approved_template_name*string

Mail template sent when an entry is approved; null when unset.

rejected_template_name*string

Mail template sent when an entry is rejected; null when unset.

updated_at*string · date-time

null when the workspace has no explicit settings row yet.

email_setup*object

Whether Waitlist emails can go out and, if not, what is missing. Computed on the server on every read.

skipped_sends*object

Emails Waitlist did not send in the last 7 days because the setup was incomplete.

Example

Request

PUT https://api.waitlist.productcraft.co/v1/workspaces/{workspace_id}/waitlist/settings
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "default_sender_domain_id": "5e1f3a2b-8c4d-4e6f-9a0b-1c2d3e4f5a6b",
  "default_heimdall_app_slug": "acme-product",
  "brand_name": "Acme",
  "brand_logo_url": "https://acme.com/logo.png",
  "primary_color": "#4F46E5",
  "notifications_via_envoi": true,
  "sender_mode": "workspace",
  "default_sender_address": "hello@mail.acme.com",
  "welcome_template_name": "waitlist-welcome",
  "approved_template_name": "waitlist-approved",
  "rejected_template_name": "waitlist-rejected"
}

Response

{
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "default_sender_domain_id": "00000000-0000-0000-0000-000000000000",
  "default_heimdall_app_slug": "string",
  "brand_name": "string",
  "brand_logo_url": "string",
  "primary_color": "string",
  "notifications_via_envoi": false,
  "sender_mode": "workspace",
  "effective_sender": {},
  "default_sender_address": "string",
  "welcome_template_name": "string",
  "approved_template_name": "string",
  "rejected_template_name": "string",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "email_setup": {},
  "skipped_sends": {}
}