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.