Routes, relays and smart hosts, OAuth2 relaying, restricted delivery and recall

Progressiverobot

Written for 6.3.4. hMailServer 6.3.7 (17 October 2026) holds a credential confined to named domains - such as a domain administrator, or an API key issued for its domains - to a public address when it changes a domain's relay host, so it cannot point the server's delivery at the server's own network, and makes a domain's or an account's rule's Send using route and Bind to address actions the server administrator's to set; an account given the serveradmin role with a list of domains is, over COM as over REST, confined to those domains, so a script's account that edits the routes or the relayer needs the role with no list. See the 6.3.7 announcement.

There are four ways this server can decide where an outbound message goes, and they are tried in a fixed order. Almost every "it went to the wrong server" question is answered by knowing that order, so this topic starts with it. It then covers the smart host and its failover, per-domain relays, routes and what they do to an unknown recipient, sending an OAuth2 token to a relay and what 6.3.4 changed about it, the COM change that is in effect only after Save(), and three things new in 6.3.4 (27 September 2026, schema 6104) that are not about where mail goes: remote domain policies (one paragraph here; the fuller treatment is Requiring TLS: MTA-STS, DANE and remote domain policies) and restricted delivery, which decide whether mail may go, and message recall, which withdraws unread copies already delivered on this server. The one thing to know first: a route is a statement about the destination and beats everything; a per-domain relay is a statement about the sender; the server-wide relayer is the fallback for mail nothing else has an opinion about.

The order of decision

When a message is ready to leave, its recipients are grouped by domain and the server asks:

Did a global rule apply the Send using route action? Then every recipient goes to that route's target host and nothing else is consulted.
Is there a route whose domain matches the recipient domain? Wildcards are allowed. The route's host, port, connection security and credentials are used.
Does the sender's local domain have a relay host of its own? That domain's relay host, port, security and credentials. Port 0 means 25.
Is a server-wide SMTP relayer configured? The relayer's host, port, security and credentials. Port 0 means 25.
Otherwise, an ordinary MX lookup for the recipient domain, then A or AAAA for each MX host.

Targets that turn out to be identical are merged: a message for four domains that all relay through one smart host opens one connection, not four. A bounce never picks up a per-domain relay, because a bounce has no envelope sender, so there is no sending domain to consult.

Since 6.3.4 one question comes before all of these for inbound mail: an address or a hosted domain routed to a webhook has each message posted to an application, instead of being delivered (deliver off) or as well (deliver on). That is a different thing from the routes below, which send a domain's mail to another mail server; mail in to a webhook has the webhook routes.

Sending through a smart host

On Windows, configure it in the Control Panel at Mail flow & delivery → Delivery of e-mail → Relayer. The Control Panel and the COM API are Windows-only; over REST, which Linux has too, the relayer's settings are keys of PUT /api/v1/settings (smtp_relayer_password is write-only).

Setting	COM name	Default	When it is wrong
SMTP relayer	`SMTPRelayer`	empty: MX lookup	A host that does not resolve gives the bounce text "The host specified as SMTP relay server could not be found" with `4.3.5`, a temporary failure, so the message is retried
Port	`SMTPRelayerPort`	`25`	Looks like a connection timeout in the SMTP log
Connection security	`SMTPRelayerConnectionSecurity`	None	Required against a host without STARTTLS defers every message
Relayer requires authentication	`SMTPRelayerRequiresAuthentication`	off	Off against a host that requires it gives `530`/`535` and the mail stays queued
Number of delivery retries	`SMTPNoOfTries`	`4`	`0` means one attempt and then a bounce
Minutes between retries	`SMTPMinutesBetweenTry`	`60`
Outbound delivery security	`SMTPConnectionSecurity`	STARTTLS (optional)	Applies to MX-resolved delivery, not to the relayer

Several smart hosts. Separate the names with a vertical bar:

smtp1.example.net|smtp2.example.net

Each name is resolved in turn and every address it resolves to is appended, giving one ordered candidate list tried top to bottom. A single name with several A records already gives that failover. All hosts in the list share the port, security and credentials. A permanent 5xx rejection is a real delivery failure and the next host is not tried: trying it would deliver the message twice if the first server had in fact accepted it.

Relaying everything through an ISP:

Open Mail flow & delivery → Delivery of e-mail → Relayer.
SMTP relayer: smtp.isp.example. Port: 587.
Connection security: STARTTLS (required) - required, not optional, so a downgrade cannot send your credentials in clear.
Tick Relayer requires authentication and fill in the user name and password.
Save changes, send one message, and read Monitoring & troubleshooting → Live logs.

The line that proves the relayer was used is:

"SMTPDeliverer - Message 41: Relaying to host smtp.isp.example."

If the message went to an MX host instead, the relayer field is empty, or a route or a per-domain relay took precedence.

Per-domain relay. Accounts & domains → Domains → Properties → Relay sets where mail from that domain leaves through. It is for a server hosting several independent domains where each has bought its own delivery provider. An empty host means the domain has no opinion. Since 6.3.7 a credential confined to named domains - such as a domain administrator, or an API key issued for its domains - may set the host to a public address only, over REST and over COM; a host on the server's own network is the server administrator's to set, and one the server administrator set stays the domain administrator's to save, since only a change of the host is judged.

Routes

A route overrides delivery for a specific recipient domain. Mail flow & delivery → Routes: type the domain and target host, press Add, then Properties for everything else. Over REST the routes are /api/v1/routes.

Field	Default	Note
Domain name	-	Wildcards are matched, so `.partner.example` works. The first* matching route in name order wins; a wildcard broader than you meant silently captures other domains
Target SMTP host, port	-, `25`	A name or a literal IP address; the `host1\\|host2` failover applies here too
Number of delivery retries	`3`	Replaces `SMTPNoOfTries`. The delivery path applies it as tries − 1, so a route set to 3 schedules 2 further attempts
Minutes between retries	`10`	Where one message has recipients on several routes, the largest count and the largest interval win
Deliver to all addresses	on	Off: only the addresses listed are routed. Off with an incomplete list is the single most common route mistake
Connection security	None	None, SSL/TLS, STARTTLS optional, STARTTLS required
Treat sender domain as local	off	Turn it on only for a domain you actually control
Treat recipient domain as local	off	On, unauthenticated senders may send to it from the Internet range

What a route does to an unknown recipient:

Route setting	Domain has a catch-all?	Address in the route's list?	Result
Deliver to all addresses	-	-	Routed
Specific addresses only	no	no	`550 Recipient not in route list.`
Specific addresses only	yes	no	Delivered to the catch-all, not routed
Specific addresses only	yes	yes	Routed; the catch-all does not intercept it

Routes also make ETRN work: when a remote site issues ETRN <domain> and a route matches, the messages held for it are released for immediate delivery.

OAuth2 to a relay

A route or the SMTP relay whose host is on OutboundOAuth2Hosts (default smtp.office365.com) is sent AUTH XOAUTH2 with the server's own token: a client-credentials token fetched from OutboundOAuth2TokenUrl with OutboundOAuth2ClientId, OutboundOAuth2ClientSecret and OutboundOAuth2Scope (default https://outlook.office365.com/.default), or OutboundOAuth2FixedToken used verbatim instead of fetching. The default host list is inert on its own: with OutboundOAuth2TokenUrl and OutboundOAuth2FixedToken both empty, no bearer is set and the delivery proceeds with LOGIN and the password, with no log line.

Since 6.3.4 the token is sent over TLS only. A route or the SMTP relay whose host is on OutboundOAuth2Hosts and whose connection security is none - or STARTTLS optional against a server that does not offer it - used to send AUTH XOAUTH2 with the token in the clear. Such a delivery now sends nothing in its place, fails with a temporary 450 4.7.0, and the error log says to set the security to TLS or STARTTLS required (HM5912); the message waits for the retries the route allows. Exchange Online offers STARTTLS on 587, so a route set up as Microsoft documents it is not affected.

Also since 6.3.4, a relay that refuses the login no longer gets the token into the bounce, which now reads hMailServer sent: AUTH XOAUTH2 <Token removed>; the logs write AUTH XOAUTH2 ***.

These are [Settings] keys, and since 6.3.4 the database is the settings store: a line edited in the file changes nothing, the stored value is used and named as HM5804, and the line is put back where the service can write the file (when a saved setting takes effect). Change them in the Control Panel, with PUT /api/v1/settings/ini/{name} or with hmctl ini set.

A COM change is in effect only after `Save()`

Since 6.3.4 a COM change to a route or an incoming relay is in effect only after the object's Save(), and a property set and never saved changes nothing; the list of objects this applies to does not name the server-wide SMTP relayer's settings. COM is Windows-only, so this concerns scripts on Windows: the COM API topic has the whole list, what an object read before the save shows, and error 7390.

Remote domain policies, in one paragraph

Since 6.3.4 (schema 6045). A route says where mail for a domain goes; a remote domain policy says what this server will and will not do when it talks to one domain it does not host, however that domain's server was found, and it applies to a routed delivery exactly as to an MX one. One record per name or pattern (bank.example, *.example, *), the most specific active one governing, holds the outbound TLS the domain demands (none, encrypted, verified or dane; a delivery that cannot meet it is deferred with 4.7.0, never sent in the clear), TLS required of its senders (530 5.7.0), a largest message (5.3.4), connection and rate ceilings (deferred with 4.4.5), whether automatic replies and forwards may go there, a recipient callout for a domain this server is a backup MX for, and gateway encryption to the partner's own key. It is server-administrator only, and GET /api/v1/remote-domains/effective?domain=mail.bank.example answers which record a delivery will use.

Restricted delivery, since 6.3.4

Schema 6084. Accounts, or a whole domain, that may only exchange mail with named domains: a school whose pupils write to the school and to nobody else. It is not a route: it decides whether mail may go, not where.

The list is the domain's: Domain.RestrictedDomains over COM, restricted_domains on GET/PUT /api/v1/domains/{domain}, the Restricted delivery tab of the Control Panel's domain dialog, the same group in the Deck's domain editor. At most 2,000 characters, names separated by commas or spaces, ASCII only, an internationalised name in its xn--... form.

Written as	Covers
`partner.example`	that domain, and nothing beneath it
`.example`	`example` and everything beneath it, anchored at a label boundary

An account follows its domain unless it says otherwise (Account.RestrictedDelivery, restricted_delivery on the account routes):

Value	Word	Meaning
0	`domain`	Follows the domain. The default
1	`restricted`	Restricted even when the domain names nothing; the account is then confined to its own domain
2	`exempt`	May exchange mail with anyone

An empty list, the default, means nothing runs, so an upgraded server delivers exactly as it did. Always allowed: the account's own domain under its own name or any alias domain, the domain's postmaster, the null sender MAIL FROM:<>, and mail this server writes itself. Other domains this server hosts are not allowed unless named.

It is enforced in three places:

Inbound, at RCPT TO. A restricted recipient whose envelope sender is not allowed is answered 550 5.7.1 <address>: this mailbox accepts mail from named domains only., per recipient, so one refused RCPT does not end the transaction. Every session is judged, authenticated or not.
Outbound, at RCPT TO. A restricted submitting account is answered 550 5.7.1 <address>: this account may send to named domains only. for a recipient outside. The webmail's POST /api/v1/me/messages answers 400 with the sentence and queues nothing.
At local delivery, for a recipient reached by expansion: a distribution list member, an alias target, a catch-all. The restricted recipient is dropped, and a non-delivery report goes to the sender only when the sender is local.

A restricted account's forward - the account forward, an account rule's forward, a Sieve redirect - to a domain not allowed is not made, and the message is still delivered to the mailbox. Its out-of-office reply is not sent to a sender who is not allowed. Every refusal is a DEBUG log line; nothing goes to the error log, since a refusal is the feature working.

Message recall within the server, since 6.3.4

Schema 6085. An unread message sent to accounts on this server can be withdrawn by its sender. Nothing does this across the Internet: a message that has left for another server is that server's. No recall notice reaches the recipients; the Sent copy's own mark is the record.

What is recorded. A message accepted from one of the server's own accounts - an authenticated SMTP submission, credited to the account that signed in, or the webmail's send - gets one row in hm_recall per recipient that resolved to a local account. Nothing is recorded for:

mail from outside, and mail this server writes itself;
an unauthenticated submission from a local IP range in a local account's name, because a recall keyed on a claim would let anybody delete mail from other people's mailboxes;
a message with a Message-ID longer than 255 characters, and a message that expires;
the 201st and later recipient rows of one sender in a rolling day.

The recall. In the webmail, Recall in the menu of a message in the Sent folder. For a program, POST /api/v1/me/recall with {"message_id": "<the Message-ID>", "sent_id": n}; it is refused with 403 on an app password. Each recipient is judged on their own:

Outcome	Meaning
`read`	Some live copy of theirs carries `\Seen`. Nothing was done: whoever has read it keeps it
`recalled`	No copy was read; every unread copy has been deleted the way the webmail deletes a message
`gone`	No copy of theirs is there any more: deleted by the reader, never delivered, or still in the queue
`failed`	The database did not answer; a later call decides them again

The answer also counts elsewhere, the To and Cc addresses whose domain this server does not host, and says in sent_marked whether the Sent copy carries the keyword $Recalled. Read is \Seen and nothing more: a POP3 client, or an IMAP client that peeks, has the message and the recall cannot know. RecallDays (recall_days on PUT /api/v1/settings) is 14 by default, 1 to 365; a domain or an account may hold a shorter window, never a longer one. There is no COM property and no Control Panel page.

What it does not do

A route does not decide whether mail may go, and restricted delivery and a remote domain policy do not decide where. A per-policy SMTP port or credential is a route's job.
Restricted delivery does not check the From header, does not filter what is already in the mailbox, and does not gate a journal rule's copy or an alias or list in the domain that reaches outside.
Recall does not reach another server, does not touch the queue, and does not recall a message submitted without authentication.
A 5xx from one smart host is not retried on the next.

Where to read more

Wiki: Routes and Relays, Settings Reference for the OutboundOAuth2* keys, APIs Reference, Diagnosing Stalled Mail
Documents at the 6.3.4 tag: RemoteDomains.md, RestrictedDelivery.md, MessageRecall.md, Upgrading.md
The public documentation: chapter 14, Routes and relays
On this forum: Being trusted by the servers you send to, the 6.3.4 release announcement, requiring TLS and remote domain policies, and diagnosing stalled mail for a message that will not leave the queue