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
| Extension | Always? | Meaning |
|---|---|---|
| SIZE | yes | The value of max_message_bytes, so a sender can decline to start rather than be cut off mid-transfer. |
| 8BITMIME | yes | Eight-bit bodies are accepted as they are. No conversion, which is also what keeps DKIM intact. |
| PIPELINING | yes | Commands may be sent in batches without waiting for each reply. |
| STARTTLS | when [tls] is setand TLS is not yet active | Correctly withdrawn after the handshake: re-offering it inside TLS is forbidden, and mxhop refuses a second STARTTLS with 503. |
| ENHANCEDSTATUSCODES | yes | Replies 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 name | Starts an ESMTP session and resets any envelope in progress. | |
| HELO name | The older form. Accepted; the reply carries no extension list. | |
| STARTTLS | Begins 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. | |
| DATA | Reads the message with dot-unstuffing until <CRLF>.<CRLF>. 10-minute timeout. Delivery is attempted before the end-of-DATA reply is sent. | |
| RSET | Discards the envelope. The session and any TLS stay up. | |
| NOOP | 250. Resets the command timeout, which is its real use. | |
| QUIT | 221 and the connection closes. | |
| VRFYEXPN | Answered 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. | |
| HELP | 214 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
| Limit | Value | Reached by |
|---|---|---|
| command timeout | 5 minutes | Silence while a command is awaited → 421 4.4.2 timeout waiting for a command |
| DATA timeout | 10 minutes | Silence inside DATA → 421 4.4.2 timeout inside DATA |
| TLS handshake | 30 seconds | A handshake that stalls, which is how a connection is held open cheaply |
| errors per session | 10 | 421 4.7.0 too many errors, goodbye. Stops a probe walking the command space on one connection. |
| recipients per message | 100 | 452 4.5.3 — temporary, so the sender tries the rest in another message |
| message size | max_message_bytes | 552 5.3.4 message larger than <n> bytes |
| command line length | bounded | 500 5.5.6 command line too long |
| reverse DNS lookup | 2 seconds | A PTR lookup on the peer that is slow is abandoned rather than delaying the session |
| onward delivery | 5 minutesper destination group | A 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
| 220 | Greeting, and again after a successful STARTTLS |
| 221 2.0.0 | Closing, 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 accepted | MAIL FROM accepted |
| 250 2.1.5 recipient accepted | RCPT TO resolved to at least one mailbox |
| 250 2.0.0 ok / reset | NOOP / RSET |
| 214 2.0.0 | HELP |
| 252 2.5.2 | VRFY or EXPN: cannot verify, will try to deliver |
| 354 | Go ahead with the message, end with a single dot |
Temporary — the sender should retry
| 421 4.3.2 | This server is shutting down; try again. Sent to anyone mid-command during a graceful stop. |
| 421 4.4.2 | Timeout waiting for a command, or inside DATA |
| 421 4.7.0 | Too many errors on this session, goodbye |
| 451 4.7.1 | An 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.1 | Nothing was delivered and nothing said why. The honest answer when every attempt failed without a usable reply. |
| 451 4.3.2 | A destination deferred, passed through with its own text and which host said it |
| 452 4.5.3 | Too many recipients for one message |
Permanent — the sender should stop
| 500 5.5.2 | Command not recognised |
| 500 5.5.6 | Command line too long |
| 501 5.1.3 | Recipient is not <local@domain> |
| 502 5.5.1 | STARTTLS is not offered here (no [tls] block) |
| 503 5.5.1 | Out 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.1 | No such address here; or an alias's own reject text; or the alias expands to no deliverable mailbox |
| 550 5.1.7 | The envelope sender is unusable, and mail from it cannot be accepted |
| 550 5.4.6 | The alias for this recipient points in a circle |
| 550 5.7.1 | Fails 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.4 | Message larger than the configured limit |
| 554 5.4.6 | Too many hops, or this message has already passed through this host |
| 554 5.5.1 | Commands 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