Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      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