/v1/workspaces/{workspace_id}/waitlist/settingsAuthUpdate 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 · uuidId of the workspace.
Request body
default_sender_domain_idstring · uuidMail domain UUID to use as default sender for Waitlist notifications. null clears the override.
Example: "5e1f3a2b-8c4d-4e6f-9a0b-1c2d3e4f5a6b"
default_heimdall_app_slugstringAuth consumer-app slug to invite approved entries into. null clears the link.
Example: "acme-product"
brand_namestringBrand name returned in the public waitlist payload. Customer frontends render it on their own signup form.
Example: "Acme"
brand_logo_urlstring · uriLogo URL returned in the public waitlist payload. Customer frontends render it on their own signup form.
Example: "https://acme.com/logo.png"
primary_colorstringPrimary brand colour as #RRGGBB
Example: "#4F46E5"
notifications_via_envoibooleanRoute 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_modeobjectWhere 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 · emailThe 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_namestringMail template name used for entry.created notifications. Must already exist in the workspace template store.
Example: "waitlist-welcome"
approved_template_namestringMail template name used for entry.approved notifications. Must already exist in the workspace template store.
Example: "waitlist-approved"
rejected_template_namestringMail 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 · uuidThe workspace.
default_sender_domain_id*string · uuidMail domain UUID used as default sender for Waitlist notifications.
default_heimdall_app_slug*stringAuth consumer-app slug approved entries are invited into.
brand_name*stringBrand name for Waitlist emails and the public info; null when unset.
brand_logo_url*stringLogo URL for Waitlist emails and the public info; null when unset.
primary_color*stringPrimary brand colour as #RRGGBB
notifications_via_envoi*booleanWhether Waitlist notifications are routed through the Mail service.
sender_mode*objectWhere 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*objectThe sender Waitlist emails actually go out from, with its live status in Mail.
default_sender_address*stringThe From used when `sender_mode` is `custom`.
welcome_template_name*stringMail template sent on sign-up; null when unset.
approved_template_name*stringMail template sent when an entry is approved; null when unset.
rejected_template_name*stringMail template sent when an entry is rejected; null when unset.
updated_at*string · date-timenull when the workspace has no explicit settings row yet.
email_setup*objectWhether Waitlist emails can go out and, if not, what is missing. Computed on the server on every read.
skipped_sends*objectEmails 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": {}
}