Lockally Domains API
Tenant-owned mail domains and DNS verification
Tenant-owned mail domains and DNS verification
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/lockally-com:lockally-com-domains-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: lockally control plane Domains API
version: 0.1.0
summary: REST API for managing tenants, domains, mailboxes, and outbound mail
description: 'The lockally control plane lets integrators and direct customers manage
everything except actual mail data flow (which uses standard JMAP / IMAP /
SMTP-submission against the data plane endpoints).
**Authentication.** All `/v1/*` endpoints require a Bearer API key in the
`Authorization` header. Keys are formatted `lk_live__`,
or `lk_test_` for a test key. Create keys in the dashboard, or with
`POST /v1/api-keys` using a key that holds `tenant:admin`.
The key''s plan is checked on every request, so a key stops working if the
account moves to a plan without API access, and works again if it moves back.
**Errors.** Failures return RFC 9457
`application/problem+json` documents.
**Scopes.** Each endpoint requires a specific scope on the presented key.
Insufficient scope returns `403` with the required scope name in `detail`.'
contact:
name: lockally support
email: support@lockally.com
license:
name: AGPL-3.0-only OR LicenseRef-LOC-Commercial
identifier: AGPL-3.0-only
servers:
- url: https://api.lockally.com
description: Production
- url: http://127.0.0.1:8081
description: Local development / spike
security:
- bearerAuth: []
tags:
- name: Domains
description: Tenant-owned mail domains and DNS verification
paths:
/v1/domains:
get:
operationId: listDomains
tags:
- Domains
summary: List domains
description: Returns every domain registered under the calling tenant.
x-required-scope: domains:read
parameters:
- name: sort
in: query
schema:
type: string
enum:
- domain
- created_at
- verified_at
default: created_at
description: Field to order by. This list holds tens of rows per account, so every column is offered and none needs an index.
- name: order
in: query
schema:
type: string
enum:
- asc
- desc
description: Defaults to desc for the default field and asc for any other. Always tie-broken on id, so the order is total.
responses:
'200':
description: Domain list
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/Domain'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
post:
operationId: createDomain
tags:
- Domains
summary: Register a domain
description: '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.'
x-required-scope: domains:write
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- domain
properties:
domain:
type: string
format: hostname
example: acme.com
responses:
'200':
description: Domain already registered to the calling tenant (idempotent).
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
'201':
description: Domain created.
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'409':
description: Domain claimed by another tenant.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/domains/{domain}:
get:
operationId: getDomain
tags:
- Domains
summary: Get a domain
x-required-scope: domains:read
parameters:
- name: domain
in: path
required: true
schema:
type: string
format: hostname
responses:
'200':
description: Domain record including the DNS instructions to publish.
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
delete:
operationId: deleteDomain
tags:
- Domains
summary: Delete a domain
description: 'Removes the domain registration. Refuses with 409 if any mailbox is
still attached, delete the mailboxes first.'
x-required-scope: domains:write
parameters:
- name: domain
in: path
required: true
schema:
type: string
format: hostname
responses:
'204':
description: Deleted.
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
'409':
description: Domain still has mailboxes attached.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/domains/{domain}/verify:
post:
operationId: verifyDomain
tags:
- Domains
summary: Force-poll DNS verification
description: 'Synchronously checks the `_lockally-verify.` 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.'
x-required-scope: domains:write
parameters:
- name: domain
in: path
required: true
schema:
type: string
format: hostname
responses:
'200':
description: Current domain state (possibly newly verified).
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
'502':
description: Upstream DNS error (timeout, server unreachable). Retry.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/v1/domains/{domain}/return-path:
parameters:
- name: domain
in: path
required: true
schema:
type: string
format: hostname
get:
operationId: getReturnPath
tags:
- Domains
summary: Get the custom Return-Path
description: 'A custom Return-Path moves the envelope sender of mail sent through the
API from this domain onto `bounces.`. 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`.'
x-required-scope: domains:read
responses:
'200':
description: Current state and the two DNS records to publish.
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnPath'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
post:
operationId: enableReturnPath
tags:
- Domains
summary: Turn on the custom Return-Path
description: 'Moves it to `pending` and returns the two records to publish on
`bounces.`. Nothing changes for mail until they are confirmed
with the verify call. The domain must be verified.
Available on every plan except Free.'
x-required-scope: domains:write
responses:
'200':
description: The Return-Path, now pending (or already active).
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnPath'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
'409':
description: The domain is not verified.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
delete:
operationId: disableReturnPath
tags:
- Domains
summary: Turn off the custom Return-Path
description: 'API mail uses the sender''s own address as the envelope sender again,
from the next message.'
x-required-scope: domains:write
responses:
'204':
description: Turned off.
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
/v1/domains/{domain}/return-path/verify:
post:
operationId: verifyReturnPath
tags:
- Domains
summary: Check the custom Return-Path records
description: 'Looks up the MX and SPF records on `bounces.`. 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.'
x-required-scope: domains:write
parameters:
- name: domain
in: path
required: true
schema:
type: string
format: hostname
responses:
'200':
description: The Return-Path with the result of the check.
content:
application/json:
schema:
$ref: '#/components/schemas/ReturnPath'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
'404':
$ref: '#/components/responses/ProblemNotFound'
'409':
description: The custom Return-Path is off. Turn it on first.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'502':
description: The mail server could not be updated. Nothing changed; retry.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'503':
description: The records are correct but the feature is not available yet. Nothing changed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
responses:
ProblemForbidden:
description: API key lacks the required scope.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
ProblemBadRequest:
description: Malformed request.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
ProblemUnauthorized:
description: Missing, malformed, or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
ProblemNotFound:
description: Resource not found under the calling tenant.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Domain:
type: object
required:
- id
- tenant_id
- domain
- verification_token
- verified
- dkim_selector
- dkim_public_record
- created_at
properties:
id:
type: string
format: uuid
tenant_id:
type: string
format: uuid
domain:
type: string
format: hostname
example: acme.com
verification_token:
type: string
example: lkv-zyj4p5qbv6i4rjm7s3wrrkr3jzo3lrvy
verified:
type: boolean
verified_at:
type: string
format: date-time
nullable: true
dkim_selector:
type: string
example: lockally
dkim_public_record:
type: string
example: v=DKIM1; k=rsa; p=MIIBIjAN...
created_at:
type: string
format: date-time
records:
type: array
description: DNS records the tenant must publish under their own DNS.
items:
$ref: '#/components/schemas/DNSRecord'
ReturnPath:
type: object
required:
- status
- host
- records
properties:
status:
type: string
enum:
- 'off'
- pending
- active
host:
type: string
example: bounces.acme.com
records:
type: array
items:
$ref: '#/components/schemas/DNSRecord'
check:
type: object
description: Present after a verify call.
properties:
mx:
type: boolean
spf:
type: boolean
requested_at:
type: string
format: date-time
verified_at:
type: string
format: date-time
Problem:
description: RFC 9457 problem-details document.
type: object
required:
- type
- status
- title
properties:
type:
type: string
format: uri
default: about:blank
status:
type: integer
title:
type: string
detail:
type: string
instance:
type: string
format: uri
DNSRecord:
type: object
required:
- type
- name
- value
- ttl
- purpose
properties:
type:
type: string
enum:
- TXT
- MX
name:
type: string
format: hostname
value:
type: string
ttl:
type: integer
example: 300
priority:
type: integer
description: MX records only.
nullable: true
purpose:
type: string
enum:
- verification
- spf
- dkim
- mx-primary
- mx-backup
- dmarc
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: lk_live_<prefix>_<secret>
description: API key, format `lk_live_<8-char-prefix>_<32-char-secret>`.
oauth2:
type: oauth2
description: 'OAuth 2.1 (authorization code + PKCE). The access token is sent as the
`Authorization: Bearer` credential, exactly like an API key, so any SDK
that accepts a bearer token works with OAuth. Discovery:
`/.well-known/oauth-authorization-server`.
'
flows:
authorizationCode:
authorizationUrl: https://api.lockally.com/oauth/authorize
tokenUrl: https://api.lockally.com/oauth/token
scopes:
inboxes:read: Read agent-accessible mailboxes and threads
inboxes:write: Send and act on agent-accessible mailboxes