mxhop

Reference · SMTP

Every command it answers and every reply it can give.

mxhop implements the receiving half of SMTP and nothing more. There is no AUTH, no submission port, no relaying for authenticated users — it accepts mail addressed to domains it was configured for, from anyone, and forwards it. That is the entire surface.

The EHLO response

EHLO sender.example
250-mx.example.com greets sender.example
250-SIZE 26214400
250-8BITMIME
250-PIPELINING
250-STARTTLS
250 ENHANCEDSTATUSCODES
ExtensionAlways?Meaning
SIZEyesThe value of max_message_bytes, so a sender can decline to start rather than be cut off mid-transfer.
8BITMIMEyesEight-bit bodies are accepted as they are. No conversion, which is also what keeps DKIM intact.
PIPELININGyesCommands may be sent in batches without waiting for each reply.
STARTTLSwhen [tls] is setand TLS is not yet activeCorrectly withdrawn after the handshake: re-offering it inside TLS is forbidden, and mxhop refuses a second STARTTLS with 503.
ENHANCEDSTATUSCODESyesReplies carry a status code like 5.7.1 alongside the three-digit one.

Not offered, deliberately: AUTH (nothing to authenticate — mxhop never relays on behalf of a user), SMTPUTF8, CHUNKING, DSN. A sender that needs any of these is not sending you ordinary inbound mail.

Commands

EHLO nameStarts an ESMTP session and resets any envelope in progress.
HELO nameThe older form. Accepted; the reply carries no extension list.
STARTTLSBegins the TLS handshake. 30-second timeout. Afterwards the session restarts from scratch — anything said before the handshake is discarded, and commands sent before it are refused with 554 5.5.1 rather than trusted.
MAIL FROM:<…>Sets the envelope sender. An empty path is the null sender, legitimate for bounces. With SRS configured, a rewritten address arriving here is verified, and a forged one is refused.
RCPT TO:<…>Resolved through the alias table immediately, so an address that does not exist is refused before the body is transmitted. Up to 100 per message.
DATAReads the message with dot-unstuffing until <CRLF>.<CRLF>. 10-minute timeout. Delivery is attempted before the end-of-DATA reply is sent.
RSETDiscards the envelope. The session and any TLS stay up.
NOOP250. Resets the command timeout, which is its real use.
QUIT221 and the connection closes.
VRFYEXPNAnswered 252 2.5.2 cannot verify, will try to deliver. Deliberate: a truthful answer is an address-harvesting oracle, and refusing outright tells an attacker which hosts are worth probing. This says nothing either way.
HELP214 with a link to the repository.

Anything else is 500 5.5.2 command not recognised, and counts toward the error limit.

Timeouts and limits

LimitValueReached by
command timeout5 minutesSilence while a command is awaited → 421 4.4.2 timeout waiting for a command
DATA timeout10 minutesSilence inside DATA → 421 4.4.2 timeout inside DATA
TLS handshake30 secondsA handshake that stalls, which is how a connection is held open cheaply
errors per session10421 4.7.0 too many errors, goodbye. Stops a probe walking the command space on one connection.
recipients per message100452 4.5.3 — temporary, so the sender tries the rest in another message
message sizemax_message_bytes552 5.3.4 message larger than <n> bytes
command line lengthbounded500 5.5.6 command line too long
reverse DNS lookup2 secondsA PTR lookup on the peer that is slow is abandoned rather than delaying the session
onward delivery5 minutesper destination groupA slow destination delays only its own group

There is no per-IP connection limit or rate limit in v0.3.0. A public MX is exposed to whatever volume arrives, and the only bounds are the per-session ones above. Connection blocklists and rate limiting are the next thing being built. In the meantime, a firewall rate limit on port 25 is a reasonable precaution.

Every reply

Replies mxhop composes itself. Where a destination refused or deferred, its words are passed through instead of being replaced — so a 550 you see may be Gmail's sentence, prefixed with which host said it.

Success and progress

220Greeting, and again after a successful STARTTLS
221 2.0.0Closing, after QUIT
250 2.0.0 delivered as <id>End of DATA: at least one recipient was delivered, or taken into the queue. The id appears in every log line about the message.
250 2.1.0 sender acceptedMAIL FROM accepted
250 2.1.5 recipient acceptedRCPT TO resolved to at least one mailbox
250 2.0.0 ok / resetNOOP / RSET
214 2.0.0HELP
252 2.5.2VRFY or EXPN: cannot verify, will try to deliver
354Go ahead with the message, end with a single dot

Temporary — the sender should retry

421 4.3.2This server is shutting down; try again. Sent to anyone mid-command during a graceful stop.
421 4.4.2Timeout waiting for a command, or inside DATA
421 4.7.0Too many errors on this session, goodbye
451 4.7.1An authentication stage ran out of its budget on a message from a p=reject domain. Never a pass — the sender retries rather than the forgery getting through.
451 4.4.1Nothing was delivered and nothing said why. The honest answer when every attempt failed without a usable reply.
451 4.3.2A destination deferred, passed through with its own text and which host said it
452 4.5.3Too many recipients for one message

Permanent — the sender should stop

500 5.5.2Command not recognised
500 5.5.6Command line too long
501 5.1.3Recipient is not <local@domain>
502 5.5.1STARTTLS is not offered here (no [tls] block)
503 5.5.1Out of order: say EHLO first, say MAIL FROM first, no accepted recipients, a message is already in progress, or TLS is already active
550 5.1.1No such address here; or an alias's own reject text; or the alias expands to no deliverable mailbox
550 5.1.7The envelope sender is unusable, and mail from it cannot be accepted
550 5.4.6The alias for this recipient points in a circle
550 5.7.1Fails DMARC and the From: domain publishes p=reject; or the domain is not one this host accepts mail for — mxhop is not an open relay
552 5.3.4Message larger than the configured limit
554 5.4.6Too many hops, or this message has already passed through this host
554 5.5.1Commands sent before the TLS handshake are not accepted

The choice of 4xx against 5xx is never incidental. A 4xx means "ask again and it may work"; a 5xx means "stop". Returning 5xx for something temporary loses mail; returning 4xx for something permanent leaves senders retrying for days. Where mxhop cannot tell, it says 4xx — the recoverable mistake.

A full session

$ openssl s_client -starttls smtp -connect mx.example.com:25 -quiet
220 mx.example.com mxhop ready
EHLO sender.example
250-mx.example.com greets sender.example
250-SIZE 26214400
250-8BITMIME
250-PIPELINING
250 ENHANCEDSTATUSCODES
# STARTTLS is gone: we are already inside it
MAIL FROM:<alice@sender.example>
250 2.1.0 sender accepted
RCPT TO:<hi@example.com>
250 2.1.5 recipient accepted
RCPT TO:<nobody@example.com>
550 5.1.1 no such address here
# refused at RCPT. the body is never transmitted for it.
DATA
354 end your message with a single dot
Subject: hello
.
250 2.0.0 delivered as 1795110377370-000003-0007
QUIT
221 2.0.0 mx.example.com closing