Relay to an account holder's own server

An account holder can keep a domain's MX here and still have some of its mail delivered on to a server they run: an Exchange, a groupware appliance, a departmental application. The server accepts the mail, filters and logs it like any incoming mail, and passes it on from a relay spool inside the account, either by connecting to the holder's server (push) or by letting that server collect it over POP3 (pull).

The feature, its two kinds of relayed address, and the choices the account holder makes are in the account docs. They do the whole setup from their panel. You have the service:mail:relay:* commands in addition: they set the same things, see what the panel doesn't show, and service:mail:relay:resync is the repair that has no screen.

Every command takes the domain's mail service, by hostname or by ID:

elpanctl service:mail:relay:status example.com

Inspect

service:mail:relay:status shows three things at once:

Section	What it shows
Settings	Whether relaying is enabled, disabled, or disabled and draining what was queued (with the time the drain began); the method; the push target and encryption, or the collection login and the number of credentials; the retention (Give Up After) and the relay log's retention.
Spool	How many messages wait, how many were not relayed because of a spam score, how many the server gave up on, and the oldest waiting message.
Drain	For push: the last attempt, the last success, the number of consecutive failures, the next attempt, and the last error the holder's server gave.

service:mail:relay:list lists the spool's messages, --folder=queue (waiting, the default), --folder=notrelayed (held back as spam) or --folder=failed (given up on), --limit=<n> at a time.

service:mail:relay:log is the relay log, newest first: every message that reached a final state, with the holder's server's reply where there was one. Narrow it with --status= (relayed, collected, not_relayed_spam, failed, expired), --mode= (both for a dual-delivery copy, only for a relay-only address), --recipient= and --sender= (a substring, e.g. @example.com), and --limit=.

service:mail:relay:list, :log and :credential:list take --format=tsv or --format=jsonl.

Set up or change

elpanctl service:mail:relay:edit example.com --enable --method=push \
  --host=mail.example.com --port=25 --tls=encrypt \
  --sasl-username=<user> --sasl-password=<password> --max-age-days=5
elpanctl service:mail:relay:edit example.com --method=pull
elpanctl service:mail:relay:edit example.com --disable

Option	Meaning
--enable, --disable	Relaying on or off for the domain. Off deletes nothing: the relayed addresses, the dual-delivery settings and the spooled mail survive, and the spool keeps draining.
--method=push or pull	We connect to the holder's server, or their server collects over POP3.
--host, --port	Push only. Where we deliver; the port is usually 25.
--tls=none, may, encrypt, verify	Push only. No encryption; encrypt when offered (the panel's Opportunistic); always encrypt (Necessary); encrypt and check the certificate against the hostname (Verified).
--sasl-username, --sasl-password	Push only. Set both when the holder's server asks us to authenticate; an empty string clears, both halves together.
--max-age-days=<1-30>	How long a message is retried, or waits to be collected, before the server gives up on it and reports it. The default is 5.

service:mail:relay:flush tries the whole spool now, for a push domain: the same as Send now in the account panel.

The common failure is at the holder's end

A push target that refuses our address, or a collector whose credential is held to addresses it no longer connects from, looks the same in the spool: mail waits silently until it expires. Drain in service:mail:relay:status shows the last error for push; for pull, a growing Waiting count with no collected rows in the log is the sign.

Collection credentials

A pull domain's server signs in with a collection credential: the username is the same for every credential of the domain and names the shared spool, and the password is shown once, at creation. The same credential can also send through the server, as the domain's relayed addresses only.

elpanctl service:mail:relay:credential:create example.com "<description>" \
  --allowed-ip=203.0.113.10 --allowed-ip=2001:db8::/64
elpanctl service:mail:relay:credential:list example.com
elpanctl service:mail:relay:credential:revoke example.com <credential-id>

--allowed-ip is repeatable and replaces the credential's list. Without it, the credential inherits the domain's own allowed-address policy; there is no way to make a credential that works from nowhere. The description is what the account holder sees in their panel. A revoked credential stops at once.

Repair

The relay is written to the mail system per address, from the panel's own records, every time one of them changes. When a domain's relayed mail behaves as though the panel and the mail system disagree, resync it:

elpanctl service:mail:relay:resync example.com --dry-run
elpanctl service:mail:relay:resync example.com
elpanctl service:mail:relay:resync --all --dry-run
elpanctl service:mail:relay:resync --all

The signs: a dual-delivery mailbox whose copies never arrive, a relay-only address that answers 550, mail spooling for an address the holder has already removed, or service:mail:relay:status saying that the drain has no target fragment for the domain on disk. --dry-run reports what disagrees and changes nothing.

The rewrite is safe at any time and on a domain that is already correct: it writes what the panel would have written anyway, removes only what the records no longer relay, and never touches the spool. A domain with relaying turned off is skipped, so a sweep with --all tears nothing down.

Where the spool lives

The spool is inside the account, so waiting mail counts against the account's storage limit (Limits). A dual-delivery copy is stored twice while it waits, once in the mailbox and once in the spool, and a long --max-age-days lets a server that is down for long fill the account's allowance.

Outside gateways in front of or behind a domain

The opposite arrangement, an outside anti-spam appliance, compliance filter or smarthost in a domain's path, is the third-party mail gateway: an incoming gateway whose MX records replace ours and whose addresses are the only ones we accept the domain's mail from, or an outgoing gateway we deliver the domain's mail through. The account holder sets it on the domain's Mail service, DNS included (account docs). It has no elpanctl command.