Domains
Read Domains for what onboarding is and when a domain is ready.
Onboard
| Call | What it does |
|---|---|
POST /v1/domains |
onboards a domain the owner already registered |
GET /v1/domains |
every domain on the account |
GET /v1/domains/{id} |
one domain, with its status |
DELETE /v1/domains/{id} |
removes it from the account |
GET /v1/account reports domain_onboarding with the modes this
deployment supports. Read the modes rather than discover one by being
refused.
Clave does not register domains. There is no registrar here.
Attach and detach
| Call | What it does |
|---|---|
POST /v1/domains/{id}/attach |
serves a site on the domain |
POST /v1/domains/{id}/detach |
stops serving it there |
Certificates and DNS are automatic on attach.
A domain is live only when its status and its ssl.status are both
active. The status goes active first, so do not tell an owner the domain
is live on that alone.
Records
| Call | What it does |
|---|---|
GET /v1/domains/{id}/records |
the DNS records of the domain |
POST /v1/domains/{id}/records |
adds one |
DELETE /v1/domains/{id}/records/{record_id} |
removes one |
These are for what the owner needs beside the site, such as mail.
Mail from the domain
| Call | What it does |
|---|---|
PUT /v1/domains/{id}/mail |
sends the site's mail to visitors from the domain |
DELETE /v1/domains/{id}/mail |
stops it |
PUT takes {"local": "hello"}, the part of the address before the @.
The domain must be active with a site on it. A domain has a mail object
only on a deployment that offers this.
The mail goes from the registrable domain: a cname domain on
www.example.com sends from example.com. On nameservers Clave writes
the DNS records. On cname the owner adds them, from mail.records: the
ones marked required at least, and a record marked only_if_none only
if the domain has no record of that name.
mail.status is pending until the mail service finds the records, then
verified. Until then the site sends no mail to visitors. failed means
it did not find them in 72 hours: PUT again to start over. paused
means the site's mail is stopped: the site then sends no mail to visitors,
and runtime mail answers mail_paused. Only Clave's staff can start it
again.
mail.paused_by says who stopped it:
| Value | Who |
|---|---|
clave |
Clave, for the bounces and complaints below |
ses |
the mail service, Amazon SES |
staff |
Clave's staff |
GET /v1/domains/{id} also gives mail.health while the domain can send,
or could before a pause:
"health": {"since": "2026-10-03T12:00:00Z", "sent": 40, "bounces": 1, "complaints": 0}
It counts the live site's mail since since: the last 7 days, or the
last time staff started the mail again, when that is later. bounces are
the mails that can never arrive (hard bounces). complaints are the mails
a reader marked as spam. Clave stops the mail when bounces is at least 5
and more than 5% of sent, or complaints is at least 2 and more than
0.5%.
The Mail tab of the site in the app marks each mail that bounced or
was marked as spam. Stop the site from sending to those addresses, then
ask for the mail to start again with POST /v1/feedback.
Mail to the owner does not change.
Plans
A plan that includes a domain cannot be fulfilled end to end today, because nothing here registers one. Clave reports which plans are sellable rather than let a surface decide for itself.