SMTP in Ferroma#

Who should read this: anyone implementing, testing or troubleshooting ferroma-smtp, and any operator trying to work out why a remote server refused their mail.

This document covers both directions of SMTP. Inbound is the listener that accepts mail from other MTAs, and the submission listener that accepting mail from your own users' mail clients. Outbound is the queue worker that resolves MX records and delivers your users' mail to remote hosts. It specifies the command set, the session state machine, the reply codes for every failure, the limits and where each one is enforced, the Received: header Ferroma prepends, the retry schedule, the 4xx-versus-5xx classification rule, and bounce generation.

Status: design specification. The ferroma-smtp crate is implemented against this document; sections marked (planned) describe behaviour that is specified but not yet shipped. Everything in this file is (planned) as of now: crates/ferroma-smtp/src/lib.rs is a skeleton declaring the server/client/MX/policy module boundaries. The configuration keys, limit values and error variants it refers to do exist — [smtp] and [limits] in config/ferroma.toml, Limits in crates/ferroma-core/src/limits.rs, FerromaError in crates/ferroma-core/src/error.rs, and the mail_queue / delivery_attempts tables in migrations/0001_initial.sql.

1. Ports and listener roles#

Config::validate() refuses to start when smtp.smtps_port != 0 and tls.enabled = false, when two active SMTP ports collide, or when smtp.port is 0. See crates/ferroma-core/src/config.rs.

Which port a connection arrived on is part of the session, not a separate code path: it selects the policy profile (whether authentication is mandatory, and whether an unauthenticated transaction may address a non-local domain).

2. Command set (§9)#

Specification §9.1 splits the command set into two phases.

Additional commands the implementation accepts, with the RFC that defines them:

Anything else is 500 5.5.2 Command unrecognized.

Command lines#

• Maximum command line: 512 octets including CRLF (RFC 5321 §4.5.3.1.4). Longer
  ⇒ 500 5.5.2 Line too long. The limit is checked before parsing, so an
  attacker cannot make the parser allocate.
• Commands are case-insensitive (mail from: is valid).
• MAIL FROM, RCPT TO and AUTH may carry ESMTP parameters
  (SIZE=, BODY=8BITMIME, SMTPUTF8, AUTH=) separated by spaces. Unknown
  parameters are ignored, per RFC 5321 §4.1.1.11.
• Unknown verbs are rejected; unknown parameters are not. That asymmetry is
  what the RFC asks for and it is what keeps a new client working against an old
  server.

3. The state machine#

Specification §9.2 gives the enum; the shipped implementation uses it verbatim, extended with the encrypted flag that STARTTLS needs.

/// crates/ferroma-smtp/src/server/state.rs
pub enum SmtpState {
    Connected,      // greeting sent, nothing received yet
    Greeted,        // EHLO/HELO accepted
    MailFrom,       // MAIL FROM accepted, no recipient yet
    RcptTo,         // at least one RCPT TO accepted
    Data,           // 354 sent, reading the dot-terminated body
    Authenticated,  // SASL succeeded (orthogonal to the five above)
}

Transitions:

                    ┌──────────────┐
   connect ────────►│  Connected   │ 220 <smtp.banner>
                    └──────┬───────┘
        EHLO/HELO ─────────┤          250-… / 250 SIZE n
                           ▼
                    ┌──────────────┐
                    │   Greeted    │◄──── RSET (from any state)
                    └──────┬───────┘
      MAIL FROM:<…> ───────┤          250 2.1.0
                           ▼
                    ┌──────────────┐
                    │   MailFrom   │
                    └──────┬───────┘
      RCPT TO:<…> ─────────┤          250 2.1.5  (repeatable)
                           ▼
                    ┌──────────────┐
                    │    RcptTo    │
                    └──────┬───────┘
         DATA ─────────────┤          354 End data with <CR><LF>.<CR><LF>
                           ▼
                    ┌──────────────┐
                    │     Data     │  (body with limits.data_timeout_secs)
                    └──────┬───────┘
        end-of-data ───────┴─────────► 250 2.0.0 Ok: queued as <id>  → Greeted
                                   └──► 4xx / 5xx                    → Greeted

Authenticated is not a position in that sequence; it is a flag that survives RSET and changes what the session is allowed to do. AUTH is legal in Greeted and later, never in Connected (503 5.5.1 Send HELO/EHLO first) and never during Data.

Guards, and the reply when a guard fires:

4. The session struct#

Specification §9.3:

/// crates/ferroma-smtp/src/server/session.rs
pub struct SmtpSession {
    /// Unique per accepted connection; also the `connection_id` log field.
    pub connection_id: Uuid,
    /// TCP peer address. Taken from `X-Forwarded-For` only when
    /// `api.trust_proxy_headers` is set and the peer is a trusted proxy.
    pub remote_addr: SocketAddr,
    /// The handler the connection is talking to.
    pub port: SmtpPort,          // Mx | Submission | Smtps
    pub state: SmtpState,
    /// The name the peer announced. Used in `Received:`, never trusted.
    pub helo: Option<String>,
    /// `true` once STARTTLS completed. Gates `require_tls_for_auth`.
    pub encrypted: bool,
    /// Set by a successful `AUTH`; the account whose quota and rate limits apply.
    pub authenticated_user: Option<UserId>,
    /// The session row created by `AuthService::open_session(SessionKind::Smtp)`.
    pub session_id: Option<SessionId>,
    /// `MAIL FROM` reverse-path, empty for a null sender (`<>`, a bounce).
    pub envelope_from: Option<String>,
    /// Accepted recipients, in order, after aliases and catch-all expansion.
    pub recipients: Vec<String>,
    /// `SIZE=` announced on `MAIL FROM`, when the client sent one.
    pub declared_size: Option<u64>,
    /// `BODY=` / `SMTPUTF8` parameters seen on `MAIL FROM`.
    pub body_8bit: bool,
    pub smtp_utf8: bool,
}

Every field that can be logged appears in the structured fields listed in specification §40 (connection_id, remote_ip, helo, authenticated_user, sender, recipient, message_id, result, duration). ferroma-core's logging module installs the subscriber that carries them.

The session is per connection and lives on one Tokio task. Nothing about it is shared, so the state machine needs no locking; the counters that are shared (connection totals, per-IP rate windows) live in the listener.

5. EHLO extensions advertised#

EHLO is answered with one line per capability, and the whole set is only sent when smtp.advertise_extensions = true; when it is false the session replies with 250-<hostname> and a bare 250 OK, which is what an ancient client that chokes on extensions needs.

AUTH is withheld entirely on a connection that is not encrypted when smtp.require_tls_for_auth = true. Advertising a mechanism the session will refuse is worse than not advertising it: it makes a client fail after sending credentials it should never have sent in the clear.

6. Open-relay policy, and why it is the default#

Specification §9.4 and §54:

recipient domain is a local domain   →  accept (subject to quota and limits)
recipient domain is anything else    →  require a successful AUTH first

Concretely, in RCPT TO handling:

Why the default is what it is. An open relay is not a configuration inconvenience; it is a machine for laundering spam that will be blacklisted within hours and will take the operator's legitimate mail down with it. Every mail administrator has seen it happen, and the damage is measured in months of deliverability, not minutes of downtime. Making the safe behaviour the default and the unsafe behaviour unreachable-by-typo is therefore worth the small amount of extra configuration: there is no allow_relay = true key to find and set by accident, and [../AGENTS.md](../AGENTS.md) §4.6 states the rule as non-negotiable.

Two adjacent policy decisions that fall out of the same reasoning:

• Local delivery does not require authentication. Otherwise no other MTA
  could deliver mail to your users at all, which is the whole point of running an
  MX.
• AUTH does not make you trustworthy for arbitrary MAIL FROM. An
  authenticated user may set any local From address they own
  (mailboxes rows with user_id = theirs); a foreign From on their own
  submission is 550 5.7.1 Sender address rejected: not owned by user.

7. Limits and where each one is enforced#

Each limit is enforced at the protocol edge and re-checked in the mail core, so talking to the API instead of SMTP cannot bypass it. crates/ferroma-core/src/limits.rs is the single definition; [limits] in config/ferroma.toml is the single source of values.

Limits::validate() refuses to boot when max_connections_per_ip > max_connections, when max_attachment_size > max_message_size, when max_message_size is 0, or when max_mime_depth is outside 1–100. A typo in [limits] therefore stops the server at boot instead of silently disabling a limit.

The per-account limits are the ones that matter for abuse: an authenticated account that has been compromised can otherwise be used as a spam cannon at whatever rate the host's uplink allows. submission_rate_limit and daily_send_limit are checked on acceptance, and the daily count is derived from mail_queue rows rather than an in-memory counter, so a restart does not reset it.

8. AUTH PLAIN and AUTH LOGIN#

Specification §15 specifies Argon2id for password storage and AUTH PLAIN / AUTH LOGIN for SMTP.

An initial-response = (RFC 4954 §4) means "empty", which is a parse error for both mechanisms: 501 5.5.4 Invalid base64 data.

Successful authentication:

1. The session decodes the credentials and calls
   AuthService::login(email, password, SessionKind::Smtp, ip, user_agent, None).
2. AuthService verifies against the stored Argon2id PHC string
   (PasswordHasher::verify), transparently re-hashes when
   PasswordHasher::needs_rehash says the stored parameters are stale, and
   records the attempt through LoginAttemptsRepository.
3. On success the session gets an authenticated_user and a SessionId from
   sessions with kind = 'smtp'.
4. The reply is 235 2.7.0 Authentication successful.

Failure replies — deliberately indistinguishable between "no such user" and "wrong password", exactly as AuthService::login makes them:

require_tls_for_auth#

Default false in config/ferroma.toml so a bare cargo run works without certificates. docker-compose.prod.yml sets FERROMA__SMTP__REQUIRE_TLS_FOR_AUTH: 'true', and a production MX should keep it there: AUTH PLAIN and AUTH LOGIN both send the password in base64, which is encoding, not encryption. Over plaintext port 587 a passive observer reads the password in the clear. With the flag on, AUTH is neither advertised nor accepted until STARTTLS completes.

Config::allows_plaintext_auth() exists so callers can ask the question without re-deriving it from the TLS flags.

9. STARTTLS, SMTPS and the submission role#

Details that are easy to get wrong and are therefore specified:

• State after STARTTLS is reset. helo, envelope_from, recipients,
  declared_size and the AUTH flag are all cleared; only connection_id and
  remote_addr survive. A client that authenticated before STARTTLS must
  authenticate again — otherwise an attacker could inject commands into the
  plaintext session and have them apply to the encrypted one.
• No command may be pipelined across STARTTLS. A STARTTLS command line
  followed by anything in the same TCP segment is an error, per RFC 3207 §6.
  Reply: 554 5.5.1 Pipelining violated then close.
• STARTTLS when tls.enabled = false is answered
  502 5.5.1 Command not implemented, and it is not advertised.
• STARTTLS when already encrypted is 503 5.5.1 TLS already active.
• A failed TLS handshake closes the connection without a reply; there is no
  plaintext fallback, which is what prevents a downgrade attack.
• Certificate material comes from tls.cert_path / tls.key_path (a PEM
  bundle: leaf followed by intermediates, and a PKCS#8 or PKCS#1 private key).
  tls.self_signed_fallback generates a certificate with rcgen at boot for
  development only — tls.allow_insecure_dev_mode has to be true as well, and
  Config::validate() enforces the pairing.
• Minimum protocol version is tls.min_version, "1.2" by default; "1.3"
  is accepted. Anything else refuses to boot.
• rustls only. No native-tls, no OpenSSL, no schannel — see
  architecture.md §8 and ../AGENTS.md §1.1.

10. The Received: header#

Inbound mail gets one Received: header prepended when smtp.add_received_header = true (the default). It is prepended, not appended: Received: headers accumulate newest-first, and the top one is the first hop that Ferroma knows about.

Received: from <helo> (<reverse-dns> [<remote-ip>])
        by <server.hostname> (Ferroma <version>)
        with ESMTPS id <connection_id>
        for <recipient>
        ; <date>

Rendered example (illustrative output):

Received: from mail.example.net (mail.example.net [203.0.113.25])
        by mail.example.com (Ferroma 0.1.0)
        with ESMTPS id 0f4c9a12-6b1e-4d3f-9a77-2c1f0e5b8d41
        for <[email protected]>
        ; Tue, 16 Sep 2026 09:12:31 +0000

Field-by-field rules:

Two things the header never contains: the peer's IP is taken from the socket, not from any header the peer sent, and no header the peer sent is ever copied into the generated line.

Authentication-Results is added separately when policy.add_auth_results or policy.add_auth_results is set; see security.md §8.

11. Outbound delivery#

Specification §10 gives the pipeline; specification §11 the queue states and the retry schedule.

 SMTP submission / Webmail / Client API
                │
                ▼
            Mail Core                renders RFC 5322, signs DKIM,
                │                    writes the Sent copy
                ▼
            mail_queue                one row per recipient
                │
                ▼
        QueueRepository::claim_due()  status pending|retry → delivering
                │
                ▼
            DNS MX                    per recipient domain
                │
                ▼
       remote MX hosts, in preference order, :25
                │
                ▼
        SMTP client (EHLO → STARTTLS if offered → MAIL → RCPT → DATA)
                │
                ├── success  ──► delivered   + delivery_attempts row
                └── failure  ──► retry | failed, per §12

11.1 Queue states and the columns that hold them#

mail_queue.status carries a CHECK constraint listing exactly these values: pending, delivering, delivered, retry, failed, cancelled.

  pending ──► delivering ──┬──► delivered
     ▲                     │
     │                     ├──► retry ──► delivering ──► …
     └─────────────────────┘
                           └──► failed   (attempts exhausted, or a 5xx)

Every attempt also writes a delivery_attempts row (queue_id, attempt, remote_mx, status_code, status_text, error, duration_ms), which is what the Admin "Delivery Logs" screen reads. Attempts are history; the queue row is state.

11.2 MX resolution#

(planned) ferroma-smtp::mx::MxResolver uses hickory-resolver (configured from [dns]).

1. Look up MX for the recipient domain.
2. Sort by preference ascending, with a stable random tie-break inside equal
   preferences so that repeated attempts do not always hit the same host first —
   which is also what RFC 5321 §5.1 recommends and what stops one dead MX from
   absorbing every retry.
3. Try hosts in order. A connection failure, a 4xx greeting, or a TLS
   failure moves to the next host in the same attempt. Only when every host has
   failed is the attempt recorded as failed.
4. Null MX. A single MX 0 . means the domain accepts no mail. That is a
   permanent failure (failed, and a bounce): 556 5.1.10 equivalent locally,
   FerromaError::Invalid.
5. No MX, but an A/AAAA record. Fall back to the address itself, per RFC
   5321 §5.1. Only when the fallback also fails is the domain undeliverable.
6. No MX and no address. FerromaError::Dns — classified per §12.5, which
   makes it temporary: a domain can be mid-registration.
7. CNAME chains are followed by the resolver, bounded by dns.attempts.
8. Timeouts come from [dns] (timeout_secs, attempts, tcp_fallback).

Connection concurrency to one host is capped by queue.max_connections_per_host (4): hammering a single remote MX with four hundred parallel connections is how a mail server gets itself blocked.

11.3 The retry schedule (§11)#

queue.retry_schedule_secs = [60, 300, 900, 3600, 21600, 86400] — one minute, five minutes, fifteen minutes, one hour, six hours, twenty-four hours. The last entry repeats until attempts reaches queue.max_attempts (12).

QueueConfig::backoff_for_attempt(attempt) is the implementation of that rule: it clamps the index to the end of the schedule, so attempt 7, 8, … all wait 86 400 seconds, and returns 60 when the schedule is empty.

Four and a half days of trying is the conventional MTA posture: long enough that a remote server's weekend outage does not bounce your user's mail, short enough that the sender eventually learns the message did not arrive. queue.retention_days (30) governs how long a delivered row is kept afterwards; it is independent of the retry window.

The dispatcher polls with queue.poll_interval_secs (10) and runs queue.workers (4) deliveries concurrently.

12. 4xx versus 5xx, and FerromaError::is_temporary()#

The classification is not decided in the SMTP layer. It is FerromaError::is_temporary() — one function, in crates/ferroma-core/src/error.rs — and it is the single source of truth behind both SMTP reply classes and the queue's retry-versus-fail decision.

pub fn is_temporary(&self) -> bool {
    matches!(
        self,
        FerromaError::Io(_)
            | FerromaError::Network(_)
            | FerromaError::Dns(_)
            | FerromaError::RateLimited
            | FerromaError::Timeout(_)
            | FerromaError::Storage(_)
            | FerromaError::Internal(_)
    )
}

The rule in one sentence: is_temporary() == true ⇒ 4xx and requeue; is_temporary() == false ⇒ 5xx and fail. A protocol layer that classifies errors itself by string-matching a message is a bug; add a variant or fix is_temporary().

12.1 Inbound: what Ferroma replies to a peer#

Two corrections to the intuition above, both deliberate:

• Over-quota is 452, not 550. A full mailbox is a temporary condition of
  the recipient, not a permanent property of the address. 550 would cause the
  sender's MTA to bounce immediately, and the user would lose the mail that
  arrived while they were over quota. RFC 3463 codes 4.2.2 as "mailbox full"
  for exactly this reason. The storage layer's StorageError::QuotaExceeded
  therefore maps to the temporary class only in the SMTP reply — it remains
  is_temporary() == false at the queue level, where the fault is genuinely the
  message's.
• 451 4.3.0 for any storage failure, including a database outage. A remote
  server that gets 451 will retry for days; a 550 would bounce the mail
  permanently because our disk was full for ten seconds.

12.2 Outbound: what a remote reply means for the queue#

12.3 Enhanced status codes#

ENHANCEDSTATUSCODES (RFC 3463) is advertised, so every reply carries a x.y.z class after the basic code. The classes Ferroma emits:

When smtp.advertise_extensions = false the enhanced code is omitted and the reply is the bare three-digit code plus the class-less text.

12.4 DSN#

DSN (RFC 3461) is advertised (planned) and the parameters on MAIL FROM (RET=FULL|HDRS, ENVID=) and RCPT TO (NOTIFY=, ORCPT=) are recorded on the queue row. NOTIFY=NEVER on a recipient suppresses the bounce for that recipient. Until it is implemented, DSN is not advertised and those parameters are ignored, which is the behaviour RFC 5321 §4.1.1.11 requires of a server that does not support them.

12.5 The complete inbound reply table#

13. Bounce generation#

When a delivery ends as failed and queue.bounce_on_failure = true, Ferroma sends a Delivery Status Notification back to the envelope sender. Specification §11 does not spell out the format, so this section is the specification.

13.1 Who gets bounced to#

The null-sender rule matters: RFC 5321 §6.1 and RFC 3464 both require that a notification have a null reverse-path, and a server that bounces a bounce will happily generate an infinite loop between two misconfigured MTAs.

13.2 The bounce is a DSN#

multipart/report; report-type=delivery-status (RFC 3462/3464), containing:

Built with ferroma_mail::MessageBuilder; the original bytes come from the Maildir by messages.storage_path. The Status: field carries the enhanced code from §12.3, so the sender's client can act on the class rather than the prose.

13.3 When a bounce is generated#

The bounce carries the original Message-ID in In-Reply-To and References, so a client can thread "Undelivered Mail Returned to Sender" with the message the user actually sent.

14. Diagnosing SMTP by hand#

Specification §44 names the tools. All of these work against a locally running server; port 25 is the inbound listener, 587 the submission listener.

# Greeting, capabilities and a full transaction, unencrypted.
swaks --server 127.0.0.1 --port 25 --from [email protected] --to [email protected] --body "test"

# The same, forcing STARTTLS.
swaks --server 127.0.0.1 --port 587 --tls --auth PLAIN --auth-user [email protected] --auth-password '…'

# By hand: type EHLO, MAIL FROM, RCPT TO, DATA.
nc 127.0.0.1 25

# Which capabilities does the submission port advertise, and does it offer STARTTLS?
openssl s_client -starttls smtp -connect 127.0.0.1:587 -crlf

# Implicit TLS on 465.
openssl s_client -connect 127.0.0.1:465

# Is the MX record the one Ferroma will use?
dig +short MX example.com

Illustrative output of the greeting and capability exchange:

220 mail.example.com Ferroma ESMTP ready
EHLO client.example.net
250-mail.example.com
250-PIPELINING
250-SIZE 26214400
250-8BITMIME
250-ENHANCEDSTATUSCODES
250-SMTPUTF8
250-STARTTLS
250-AUTH PLAIN LOGIN
250 HELP
MAIL FROM:<[email protected]>
250 2.1.0 Ok
RCPT TO:<[email protected]>
250 2.1.5 Ok
DATA
354 End data with <CR><LF>.<CR><LF>
Subject: test

hello
.
250 2.0.0 Ok: queued as 4821
QUIT
221 2.0.0 Bye

For "mail is not arriving" and "the queue is growing", see the symptom-keyed command list in deployment.md §11.

15. Related documents#