# 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](https://www.rfc-editor.org/rfc/rfc6531.html),
[RFC 3030](https://www.rfc-editor.org/rfc/rfc3030.html) and
[RFC 3461](https://www.rfc-editor.org/rfc/rfc3461.html).

## 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`:

```json
"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](proxy-protocol.md) when a TCP load balancer
must preserve the client address before Bongo accepts the SMTP connection.