Skip to content
Knobs Docs

Domains, mailboxes & aliases

Every workspace gets a <subdomain>.knobs.io mail domain at creation; admins can add a custom domain, verify its DNS, and manage the mailboxes on it. Members can claim extra addresses (aliases) on any verified workspace domain when the admin enables the feature.

All routes are workspace-scoped and accept a session JWT or API key. Reads are member-level; domain and mailbox mutations require admin.

Domains

Section titled “Domains”
Endpoint Description
GET /v1/workspaces/{wid}/domains List the workspace’s mail domains
POST /v1/workspaces/{wid}/domains Add a custom domain {domain} (admin) → the DNS records to publish
GET /v1/workspaces/{wid}/domains/{did} Domain + records + per-check verification status
POST /v1/workspaces/{wid}/domains/{did}/verify Re-check DKIM/SPF/DMARC/MX + ownership now (admin)
DELETE /v1/workspaces/{wid}/domains/{did} Remove a custom domain; disables its mailboxes (admin)

Add and verify a custom domain

Section titled “Add and verify a custom domain”
Terminal window
curl -X POST https://api.knobs.io/v1/workspaces/{wid}/domains \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.com"}'

The 201 response includes the DNS records to publish (verification TXT, DKIM, SPF, DMARC, MX). Publish them, then:

Terminal window
curl -X POST -H "Authorization: Bearer knak_..." \
  https://api.knobs.io/v1/workspaces/{wid}/domains/{did}/verify

The response returns the domain with each check’s current status. Verification is also re-polled automatically. Sending and mailbox creation require a verified domain (409 failed_precondition otherwise).

Mailboxes

Section titled “Mailboxes”

A mailbox binds a local part on a domain to a member — it’s a deliverable address.

Endpoint Description
GET /v1/workspaces/{wid}/domains/{did}/mailboxes List mailboxes on one domain
POST /v1/workspaces/{wid}/domains/{did}/mailboxes Create {localPart, uid} on a verified domain (admin)
GET /v1/workspaces/{wid}/mailboxes List workspace mailboxes; ?mine=true narrows to your active send-from addresses (the compose From picker)
DELETE /v1/workspaces/{wid}/mailboxes/{mid} Disable a mailbox (admin) — never hard-deleted, existing messages still reference it
Terminal window
curl -H "Authorization: Bearer knak_..." \
  "https://api.knobs.io/v1/workspaces/{wid}/mailboxes?mine=true"

Per-user aliases

Section titled “Per-user aliases”

Members can claim additional local parts as their own aliases on any verified workspace domain, when the workspace-wide toggle is on.

Endpoint Description
GET /v1/workspaces/{wid}/aliases Your addresses (primary + active aliases) plus {enabled, domain, domains}
POST /v1/workspaces/{wid}/aliases Claim {localPart, domainId?} — the default domain when domainId is omitted
POST /v1/workspaces/{wid}/aliases:check Live availability {localPart, domainId?} → {status} — one of available, reserved, mine, taken, invalid (always 200)
DELETE /v1/workspaces/{wid}/aliases/{mid} Remove one of your own aliases (never your primary)
PATCH /v1/workspaces/{wid}/settings/email-aliases Admin toggle {enabled} for the whole workspace

Check, then claim

Section titled “Check, then claim”
Terminal window
curl -X POST https://api.knobs.io/v1/workspaces/{wid}/aliases:check \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{"localPart": "press"}'
{ "status": "available" }
Terminal window
curl -X POST https://api.knobs.io/v1/workspaces/{wid}/aliases \
  -H "Authorization: Bearer knak_..." \
  -H "Content-Type: application/json" \
  -d '{"localPart": "press"}'

Claiming a reserved local part returns 422 invalid_argument; claiming while the feature is off returns 409 failed_precondition.

Section titled “Related”
  • Mail — sending and reading messages on these addresses.
  • Workspaces & members — the default-domain switch lives on PATCH /v1/workspaces/{wid}.