bongo/docs/smtp.md

SMTP extensions

Bongo keeps the classic HELO/MAIL/RCPT/DATA path for old clients and advertises ESMTP extensions after EHLO. The server advertises 8BITMIME and SMTPUTF8 only when the corresponding configuration is enabled. SMTPUTF8 is accepted as a MAIL FROM parameter only after EHLO; non-ASCII envelope addresses require it and are validated as UTF-8.

BODY=8BITMIME is recorded with the queued message and is sent to a remote peer only when that peer advertises 8BITMIME. Bongo implements bounded BDAT chunks and advertises CHUNKING; chunk and complete-message limits are enforced before a message is committed. BINARYMIME remains unsupported, so BODY=BINARYMIME is rejected explicitly instead of silently treating binary data as a normal DATA message.

Outgoing SMTP uses the peer's advertised SIZE, 8BITMIME and SMTPUTF8 capabilities. Bongo normalizes internationalized domain names with IDNA2008 and stores and transmits the resulting lower-case A-label. The local part is left untouched; only a non-ASCII local part therefore requires SMTPUTF8. The same normalization is applied to hosted domains, aliases, TLS names, DKIM/DMARC material, MX lookup, queued envelopes, Web composition and external SMTP relays. Invalid or transitional-only domain spellings are rejected instead of being mapped differently by individual components.

For example, user@bücher.example is persisted and sent as user@xn--bcher-kva.example. Configuration files may contain either the Unicode spelling or its A-label; synchronization writes the canonical A-label to the configuration store.

Relevant standards are RFC 6531, RFC 3030 and RFC 3461.

Connection timeout

The socket_timeout value in the smtp configuration limits each blocked read or write operation on an accepted SMTP connection. Activity therefore starts a fresh timeout for the next protocol operation: a person may enter commands slowly in Telnet, but an abandoned connection cannot occupy an SMTP worker indefinitely. The default is 300 seconds, matching Postfix's normal smtpd_timeout; values from 1 through 3600 seconds are accepted. Bongo rejects zero rather than treating it as an unlimited connection.

When the projected number of active SMTP connection threads reaches stress_load_percent of max_thread_load, a newly accepted connection uses stress_socket_timeout instead. The defaults are 80 percent and 10 seconds, following Postfix's normal-versus-overload timeout model. Existing sessions retain the timeout selected when they were accepted, while new sessions return to the normal value automatically as load falls. The shorter policy also covers the PROXY header and TLS negotiation performed after accept.

Trusted downstream proxy metadata

Bongo can preserve the original SMTP client's connection address when it delivers mail to a trusted downstream SMTP or LMTP service. All three options below are empty by default. Their entries match an exact transport hostname, an exact IPv4 address, or an IPv4 CIDR such as 172.16.11.0/24:

"xclient_trusted_destinations": ["smtp-filter.example.test"],
"xforward_trusted_destinations": ["172.16.11.20"],
"proxy_header_trusted_destinations": ["172.16.11.0/24"]

xclient_trusted_destinations and xforward_trusted_destinations permit the Postfix XCLIENT and XFORWARD protocol extensions. Bongo still sends either command only when the connected peer advertises the extension and its supported attributes. These options name destination servers, not networks from which SMTP clients are accepted.

proxy_header_trusted_destinations is the compatibility fallback for servers which cannot negotiate either extension. For a matching destination Bongo adds X-Client-Addr and X-Forwarded-Addr to that delivery only. The fallback headers are suppressed when the original address was already transferred by XCLIENT or XFORWARD. User-supplied copies of these headers are removed on SMTP input, so the downstream service receives only Bongo-generated values.

Do not configure Internet destinations or a catch-all network such as 0.0.0.0/0. The metadata exposes the original client address and downstream software may treat it as trusted. This fallback applies to Bongo's direct SMTP/LMTP delivery path; authenticated external-account relay providers never receive these headers.

These outgoing metadata options are independent of incoming HAProxy PROXY protocol. See proxy-protocol.md when a TCP load balancer must preserve the client address before Bongo accepts the SMTP connection.