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.

      Custom Return-Path

      By default, API mail carries a Lockally Return-Path: bounces come back to us, and the envelope sender a receiving server sees is ours rather than yours.

      A custom Return-Path moves it to bounces.<yourdomain>, so the envelope sender is on your own domain.

      Available on every paid plan. Free returns 403 Upgrade required.

      Why it is worth doing

      The Return-Path is the address a receiving server checks SPF against, not the From header. With the default, SPF passes for a Lockally domain and your domain is aligned by DKIM only.

      Moving it to your own subdomain gives you SPF alignment as well, so DMARC has two independent reasons to pass instead of one. That is the whole benefit, and it matters most if you intend to move your DMARC policy past p=none.

      Turning it on

      POST /v1/domains/{domain}/return-path        scope: domains:write

      The domain must already be verified, or you get:

      {
        "status": 409,
        "title": "Domain not verified",
        "detail": "Verify yourcompany.com before setting up a custom Return-Path."
      }

      Nothing changes for your mail yet. Enabling moves the domain to pending and hands you two records to publish.

      The two records

      Both on the bounces subdomain:

      Type Host Value
      MX bounces mx1.lockally.com. priority 10
      TXT bounces v=spf1 include:_spf.lockally.com ~all

      Both are required, and they do different jobs. The MX makes bounce reports reach us, so delivery events keep working. The SPF record authorises Lockally for the subdomain, which is now what receiving servers check. Publish one without the other and you get either bounces going nowhere or SPF failing on every message.

      Confirming them

      POST /v1/domains/{domain}/return-path/verify     scope: domains:write

      The response carries a check object saying which of the two we can see:

      {
        "status": "pending",
        "host": "bounces.yourcompany.com",
        "check": { "mx": true, "spf": false }
      }

      Only when both are true does the status become active and the send worker start using it.

      The three states

      status
      off Never enabled, or turned off
      pending Enabled, records not confirmed. Mail is unchanged
      active Confirmed, and API mail now uses your Return-Path

      Read it with GET /v1/domains/{domain}/return-path.

      That pending row is the safety property worth noting: a half-finished setup cannot break your mail, because nothing switches over until both records verify.

      Turning it off

      DELETE /v1/domains/{domain}/return-path      scope: domains:write

      Reverts to the default Return-Path immediately. Safe at any time, and the obvious first move if bounce handling starts misbehaving after a DNS change.

      You can then remove the two DNS records, though leaving them is harmless.