Domains
Register a sending domain, verify its DNS, and manage its Return-Path.
Every endpoint needs Authorization: Bearer lk_live_.... See
Conventions for headers, status codes
and error shape.
List domains
GET /v1/domains · scope domains:read
Returns every domain registered under the calling tenant.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
sort |
query | string (domain, created_at, verified_at) |
Field to order by. This list holds tens of rows per account, so every column is offered and none needs an index. |
order |
query | string (asc, desc) |
Defaults to desc for the default field and asc for any other. Always tie-broken on id, so the order is total. |
Response 200
Domain list
| Field | Type | Notes |
|---|---|---|
data |
array of Domain | Required. |
Errors: 401, 403
Register a domain
POST /v1/domains · scope domains:write
Registers a new domain for the calling tenant. Generates a DKIM
keypair and verification token. Returns DNS instructions the tenant
must publish under their own DNS (verification TXT, SPF include,
DKIM TXT, MX records to mx1/mx2.lockally.com, DMARC seed).
Idempotent, re-posting the same domain returns the existing record with the same DKIM keys and token (regenerating would break the tenant’s published DNS). Returns 200 on idempotent hit, 201 on first create.
Returns 409 if the domain is already claimed by a different tenant.
Request body
| Field | Type | Notes |
|---|---|---|
domain |
string | Required. |
Response 200
Domain already registered to the calling tenant (idempotent).
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
domain |
string | Required. |
verification_token |
string | Required. |
verified |
boolean | Required. |
verified_at |
string | |
dkim_selector |
string | Required. |
dkim_public_record |
string | Required. |
created_at |
string | Required. |
records |
array of DNSRecord | DNS records the tenant must publish under their own DNS. |
Errors: 400, 401, 403, 409
Get a domain
GET /v1/domains/{domain} · scope domains:read
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
domain |
path | string | Required. |
Response 200
Domain record including the DNS instructions to publish.
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
domain |
string | Required. |
verification_token |
string | Required. |
verified |
boolean | Required. |
verified_at |
string | |
dkim_selector |
string | Required. |
dkim_public_record |
string | Required. |
created_at |
string | Required. |
records |
array of DNSRecord | DNS records the tenant must publish under their own DNS. |
Errors: 401, 403, 404
Delete a domain
DELETE /v1/domains/{domain} · scope domains:write
Removes the domain registration. Refuses with 409 if any mailbox is still attached, delete the mailboxes first.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
domain |
path | string | Required. |
Response 204
Deleted.
Errors: 401, 403, 404, 409
Get the custom Return-Path
GET /v1/domains/{domain}/return-path · scope domains:read
A custom Return-Path moves the envelope sender of mail sent through the
API from this domain onto bounces.<domain>. Bounce reports then come
back to Lockally instead of the sending mailbox, and a bounce that
arrives after delivery marks the message bounced, suppresses the
address and fires delivery.bounced. Mail sent from webmail or mail
apps is not affected. DKIM stays signed by the domain itself.
status is off, pending (records not confirmed yet) or active.
Response 200
Current state and the two DNS records to publish.
| Field | Type | Notes |
|---|---|---|
status |
string (False, pending, active) |
Required. |
host |
string | Required. |
records |
array of DNSRecord | Required. |
check |
object | Present after a verify call. |
requested_at |
string | |
verified_at |
string |
Errors: 401, 403, 404
Turn on the custom Return-Path
POST /v1/domains/{domain}/return-path · scope domains:write
Moves it to pending and returns the two records to publish on
bounces.<domain>. Nothing changes for mail until they are confirmed
with the verify call. The domain must be verified.
Available on every plan except Free.
Response 200
The Return-Path, now pending (or already active).
| Field | Type | Notes |
|---|---|---|
status |
string (False, pending, active) |
Required. |
host |
string | Required. |
records |
array of DNSRecord | Required. |
check |
object | Present after a verify call. |
requested_at |
string | |
verified_at |
string |
Errors: 401, 403, 404, 409
Turn off the custom Return-Path
DELETE /v1/domains/{domain}/return-path · scope domains:write
API mail uses the sender’s own address as the envelope sender again, from the next message.
Response 204
Turned off.
Errors: 401, 403, 404
Check the custom Return-Path records
POST /v1/domains/{domain}/return-path/verify · scope domains:write
Looks up the MX and SPF records on bounces.<domain>. Returns 200
either way: while a record is missing the status stays pending and
check says which one. Once both are found the Return-Path becomes
active and the send path starts using it.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
domain |
path | string | Required. |
Response 200
The Return-Path with the result of the check.
| Field | Type | Notes |
|---|---|---|
status |
string (False, pending, active) |
Required. |
host |
string | Required. |
records |
array of DNSRecord | Required. |
check |
object | Present after a verify call. |
requested_at |
string | |
verified_at |
string |
Errors: 401, 403, 404, 409, 502, 503
Force-poll DNS verification
POST /v1/domains/{domain}/verify · scope domains:write
Synchronously checks the _lockally-verify.<domain> TXT record
against the stored verification token. Returns 200 either way:
the returned verified boolean tells you whether DNS now confirms.
Caller polls until verified: true. A later version may have the platform
auto-polls and fires a domain.verified webhook.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
domain |
path | string | Required. |
Response 200
Current domain state (possibly newly verified).
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
domain |
string | Required. |
verification_token |
string | Required. |
verified |
boolean | Required. |
verified_at |
string | |
dkim_selector |
string | Required. |
dkim_public_record |
string | Required. |
created_at |
string | Required. |
records |
array of DNSRecord | DNS records the tenant must publish under their own DNS. |
Errors: 401, 403, 404, 502