Lockally Domains API

Tenant-owned mail domains and DNS verification

GitHub OpenAPI

Operations 9

GET /v1/domains List domains #
POST /v1/domains Register a domain #
GET /v1/domains/{domain} Get a domain #
DELETE /v1/domains/{domain} Delete a domain #
POST /v1/domains/{domain}/verify Force-poll DNS verification #
GET /v1/domains/{domain}/return-path Get the custom Return-Path #
POST /v1/domains/{domain}/return-path Turn on the custom Return-Path #
DELETE /v1/domains/{domain}/return-path Turn off the custom Return-Path #
POST /v1/domains/{domain}/return-path/verify Check the custom Return-Path records #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/lockally-com:lockally-com-domains-api"
All apis
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.

Get an API 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 Specification

lockally-com-domains-api-openapi.yml Raw ↑
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