📛 NAME
smtp - Postfix SMTP+LMTP client
🚀 Quick Reference
| Use Case | Command | Description |
|---|
| 📬 Deliver mail via SMTP | smtp [flags=DORX] | Standard SMTP delivery to remote MX hosts |
| 🔗 Deliver mail via LMTP | smtp [flags=DORX] | LMTP delivery using unix:path or inet:host:port syntax |
| 📑 Add Delivered‑To header | flags=D | Prepend Delivered‑To: recipient (requires single‑recipient mode) |
| 📑 Add X‑Original‑To header | flags=O | Prepend X‑Original‑To: recipient (requires single‑recipient mode) |
| 📬 Add Return‑Path header | flags=R | Prepend Return‑Path: <sender> |
| ✅ Mark delivery as final | flags=X | DSN status changes from “relayed” to “delivered” |
📋 SYNOPSIS
smtp [generic Postfix daemon options] [flags=DORX]
📖 DESCRIPTION
The Postfix SMTP+LMTP client implements the SMTP and LMTP mail delivery protocols. It processes message delivery requests from the queue manager. Each request specifies a queue file, a sender address, a domain or host to deliver to, and recipient information. This program expects to be run from the master(8) process manager.
The SMTP+LMTP client updates the queue file and marks recipients as finished, or it informs the queue manager that delivery should be tried again at a later time. Delivery status reports are sent to the bounce(8), defer(8) or trace(8) daemon as appropriate.
The SMTP+LMTP client looks up a list of mail exchanger addresses for the destination host, sorts the list by preference, and connects to each listed address until it finds a server that responds.
When a server is not reachable, or when mail delivery fails due to a recoverable error condition, the SMTP+LMTP client will try to deliver the mail to an alternate host.
After a successful mail transaction, a connection may be saved to the scache(8) connection cache server, so that it may be used by any SMTP+LMTP client for a subsequent transaction.
By default, connection caching is enabled temporarily for destinations that have a high volume of mail in the active queue. Connection caching can be enabled permanently for specific destinations.
🌐 SMTP DESTINATION SYNTAX
The Postfix SMTP+LMTP client supports multiple destinations separated by comma or whitespace (Postfix 3.5 and later). SMTP destinations have the following form:
domainname
domainname:port
[hostname]
[hostname]:port
[address]
[address]:port
- domainname — Look up mail exchangers for the domain, connect to default port (smtp).
- domainname:port — Look up mail exchangers, connect to specified port.
- [hostname] — Look up address of the specified host, connect to default port.
- [hostname]:port — Look up address, connect to specified port.
- [address] — Connect to the specified address, default port. IPv6 must be formatted as
[ipv6:address].
- [address]:port — Connect to address and port.
🔗 LMTP DESTINATION SYNTAX
The Postfix SMTP+LMTP client supports multiple destinations separated by comma or whitespace (Postfix 3.5 and later). LMTP destinations have the following form:
unix:pathname
inet:hostname
inet:hostname:port
inet:[address]
inet:[address]:port
- unix:pathname — Connect to local UNIX-domain server bound to the specified pathname. If chrooted, absolute path is relative to Postfix queue directory.
- inet:hostname — Connect to TCP port defined as
lmtp in services(4) (or lmtp_tcp_port, default 24).
- inet:hostname:port — Connect to specified port.
- inet:[address] — Connect to IPv4/IPv6 address, default port.
- inet:[address]:port — Connect to address and port.
📨 SINGLE‑RECIPIENT DELIVERY
By default, the Postfix SMTP+LMTP client delivers mail to multiple recipients per delivery request. To prevent multiple recipients (e.g., when prepending Delivered‑To: or X‑Original‑To: headers), set:
transport_destination_recipient_limit = 1
where transport is the name in the first column of master.cf for this delivery service.
⚙️ COMMAND ATTRIBUTE SYNTAX
flags=DORX (optional) — Optional message processing flags.
- D — Prepend
Delivered‑To: recipient header with envelope recipient address. Requires transport_destination_recipient_limit = 1. Also enforces loop detection (case‑insensitive compare). Available since Postfix 3.5.
- O — Prepend
X‑Original‑To: recipient header with the recipient address as given to Postfix. Requires single‑recipient mode. Available since Postfix 3.5.
- R — Prepend
Return‑Path: <sender> header with envelope sender address. Available since Postfix 3.5.
- X — Mark delivery as final. Changes DSN status from “relayed” to “delivered”. Available since Postfix 3.5.
🔒 SECURITY
The SMTP+LMTP client is moderately security‑sensitive. It talks to SMTP or LMTP servers and to DNS servers on the network. The SMTP+LMTP client can be run chrooted at fixed low privilege.
📜 STANDARDS
RFC 821, 822, 1651, 1652, 1870, 2033, 2034, 2045, 2046, 2554, 2821, 2920, 3207, 3461, 3463, 4954, 5321, 6531, 6533, 7672.
🩺 DIAGNOSTICS
Problems and transactions are logged to syslogd(8) or postlogd(8). Corrupted message files are marked so the queue manager can move them to the corrupt queue. Depending on notify_classes, the postmaster is notified of bounces, protocol problems, and other trouble.
🐛 BUGS
- SMTP and LMTP connection reuse for TLS (without closing the connection) is not supported before Postfix 3.4.
- SMTP and LMTP connection reuse assumes that SASL credentials are valid for all destinations that map onto the same IP address and TCP port.
⚙️ CONFIGURATION PARAMETERS
Before Postfix 2.3, the LMTP client was a separate program with limited functionality. Most smtp_xxx parameters have an lmtp_xxx mirror. Changes to main.cf are picked up automatically; use postfix reload to speed up. See postconf(5) for details.
🔧 COMPATIBILITY CONTROLS
- ignore_mx_lookup_error (no) — Ignore DNS MX lookups that produce no response.
- smtp_always_send_ehlo (yes) — Always send EHLO at start of SMTP session.
- smtp_never_send_ehlo (no) — Never send EHLO.
- smtp_defer_if_no_mx_address_found (no) — Defer delivery when no MX record resolves to IP.
- smtp_line_length_limit (998) — Max length of header/body lines sent via SMTP.
- smtp_pix_workaround_delay_time (10s) — Pause before sending
.<CR><LF> for PIX firewall workaround.
- smtp_pix_workaround_threshold_time (500s) — How long a message must be queued before turning on PIX workaround.
- smtp_pix_workarounds (disable_esmtp, delay_dotcrlf) — List of workarounds for CISCO PIX firewall bugs.
- smtp_pix_workaround_maps (empty) — Per‑destination workarounds by remote server address.
- smtp_quote_rfc821_envelope (yes) — Quote addresses in MAIL FROM and RCPT TO as per RFC 5321.
- smtp_reply_filter (empty) — Transform replies from remote SMTP servers line by line.
- smtp_skip_5xx_greeting (yes) — Skip servers that greet with 5XX.
- smtp_skip_quit_response (yes) — Do not wait for QUIT response.
- smtp_skip_4xx_greeting (yes, Postfix ≤2.0) — Skip servers that greet with 4XX.
- smtp_discard_ehlo_keyword_address_maps (empty, Postfix 2.2+) — Per‑address list of EHLO keywords to ignore.
- smtp_discard_ehlo_keywords (empty, Postfix 2.2+) — List of EHLO keywords to ignore.
- smtp_generic_maps (empty, Postfix 2.2+) — Address rewriting tables for outgoing mail.
- smtp_cname_overrides_servername (version dependent, Postfix 2.2.9+) — Replace server name with CNAME for logging, SASL, TLS policy.
- lmtp_discard_lhlo_keyword_address_maps (empty, Postfix 2.3+) — Per‑address LHLO keywords to ignore.
- lmtp_discard_lhlo_keywords (empty, Postfix 2.3+) — List of LHLO keywords to ignore.
- send_cyrus_sasl_authzid (no, Postfix 2.4.4+) — Do not send SASL authorization ID.
- smtp_header_checks (empty, Postfix 2.5+) — Restricted header_checks tables.
- smtp_mime_header_checks (empty, Postfix 2.5+) — Restricted mime_header_checks tables.
- smtp_nested_header_checks (empty, Postfix 2.5+) — Restricted nested_header_checks tables.
- smtp_body_checks (empty, Postfix 2.5+) — Restricted body_checks tables.
- tcp_windowsize (0, Postfix 2.6+) — Workaround for routers breaking TCP window scaling.
- smtp_dns_resolver_options (empty, Postfix 2.8+) — DNS resolver options.
- smtp_per_record_deadline (no, Postfix 2.9+) — Time limit per complete record instead of per syscall.
- smtp_send_dummy_mail_auth (no, Postfix 2.9+) — Append
AUTH=<> to MAIL FROM in SASL sessions.
- smtp_dns_support_level (empty, Postfix 2.11+) — Level of DNS support.
- smtp_delivery_status_filter ($default_delivery_status_filter, Postfix 3.0+) — Filter for delivery status codes.
- smtp_dns_reply_filter (empty, Postfix 3.0+) — Filter for DNS lookup results.
- smtp_balance_inet_protocols (yes, Postfix 3.3+) — Ensure client can try both IPv4 and IPv6 before hitting smtp_mx_address_limit.
- info_log_address_format (external, Postfix 3.5+) — Address form for non‑debug logging.
- dnssec_probe (ns:., Postfix 3.6+) — DNS query type and name to probe DNSSEC availability.
- known_tcp_ports (lmtp=24, smtp=25, smtps=submissions=465, submission=587) — Avoids services(5) lookups.
📄 MIME PROCESSING CONTROLS
- disable_mime_output_conversion (no, Postfix 2.0+) — Disable conversion of 8BITMIME to 7BIT.
- mime_boundary_length_limit (2048) — Max length of MIME multipart boundary strings.
- mime_nesting_limit (100) — Max recursion level for MIME processor.
🔍 EXTERNAL CONTENT INSPECTION CONTROLS
- smtp_send_xforward_command (no, Postfix 2.1+) — Send XFORWARD command when server announces support.
🔑 SASL AUTHENTICATION CONTROLS
- smtp_sasl_auth_enable (no) — Enable SASL authentication.
- smtp_sasl_password_maps (empty) — Lookup tables with username:password per sender/remote host.
- smtp_sasl_security_options (noplaintext, noanonymous) — SASL security options.
- smtp_sasl_mechanism_filter (empty, Postfix 2.2+) — Filter for offered SASL mechanisms.
- smtp_sender_dependent_authentication (no, Postfix 2.3+) — Enable sender‑dependent authentication (disables connection caching).
- smtp_sasl_path (empty, Postfix 2.3+) — Implementation‑specific info passed to SASL plug‑in.
- smtp_sasl_type (cyrus, Postfix 2.3+) — SASL plug‑in type.
- smtp_sasl_auth_cache_name (empty, Postfix 2.5+) — Table to prevent repeated auth failures.
- smtp_sasl_auth_cache_time (90d, Postfix 2.5+) — Max age of cache entry.
- smtp_sasl_auth_soft_bounce (yes, Postfix 2.5+) — Defer delivery on 535 reply instead of bouncing.
- smtp_send_dummy_mail_auth (no, Postfix 2.9+) — Append
AUTH=<> to MAIL FROM.
🔐 STARTTLS SUPPORT CONTROLS
Detailed information in TLS_README.
- smtp_tls_security_level (empty) — Default TLS security level; overrides obsolete parameters.
- smtp_sasl_tls_security_options ($smtp_sasl_security_options) — SASL options for TLS sessions.
- smtp_starttls_timeout (300s) — Time limit for TLS handshake.
- smtp_tls_CAfile (empty) — File with CA certificates.
- smtp_tls_CApath (empty) — Directory with CA certificates.
- smtp_tls_cert_file (empty) — RSA certificate file.
- smtp_tls_mandatory_ciphers (medium) — Minimum cipher grade for mandatory TLS.
- smtp_tls_exclude_ciphers (empty) — Ciphers to exclude at all levels.
- smtp_tls_mandatory_exclude_ciphers (empty) — Additional ciphers to exclude at mandatory levels.
- smtp_tls_dcert_file (empty) — DSA certificate file.
- smtp_tls_dkey_file ($smtp_tls_dcert_file) — DSA private key file.
- smtp_tls_key_file ($smtp_tls_cert_file) — RSA private key file.
- smtp_tls_loglevel (0) — Additional TLS logging.
- smtp_tls_note_starttls_offer (no) — Log hostname offering STARTTLS when TLS not enabled.
- smtp_tls_policy_maps (empty) — Per‑destination TLS policy.
- smtp_tls_mandatory_protocols (see
postconf -d) — TLS protocols for mandatory encryption.
- smtp_tls_scert_verifydepth (9) — Verification depth for server certificates.
- smtp_tls_secure_cert_match (nexthop, dot‑nexthop) — Certificate peername matching for “secure” level.
- smtp_tls_session_cache_database (empty) — TLS session cache file.
- smtp_tls_session_cache_timeout (3600s) — Cache expiration time.
- smtp_tls_verify_cert_match (hostname) — Certificate peername matching for “verify” level.
- tls_daemon_random_bytes (32) — Pseudo‑random bytes requested from tlsmgr.
- tls_high_cipherlist (see
postconf -d) — OpenSSL cipherlist for high grade.
- tls_medium_cipherlist (see
postconf -d) — For medium or higher.
- tls_low_cipherlist (see
postconf -d) — For low or higher.
- tls_export_cipherlist (see
postconf -d) — For export or higher.
- tls_null_cipherlist (eNULL:!aNULL) — For NULL grade (authentication only).
- smtp_sasl_tls_verified_security_options ($smtp_sasl_tls_security_options, Postfix 2.4+) — SASL options for TLS with verified server certificate.
- smtp_tls_fingerprint_cert_match (empty, Postfix 2.5+) — Acceptable server certificate fingerprints for “fingerprint” level.
- smtp_tls_fingerprint_digest (see
postconf -d, Postfix 2.5+) — Digest algorithm for fingerprints.
- smtp_tls_protocols (see
postconf -d, Postfix 2.6+) — TLS protocols for opportunistic encryption.
- smtp_tls_ciphers (medium, Postfix 2.6+) — Minimum cipher grade for opportunistic TLS.
- smtp_tls_eccert_file (empty, Postfix 2.6+) — ECDSA certificate file.
- smtp_tls_eckey_file ($smtp_tls_eccert_file, Postfix 2.6+) — ECDSA private key file.
- smtp_tls_block_early_mail_reply (no, Postfix 2.7+) — Detect mail hijacking attack (CVE‑2009‑3555).
- tls_disable_workarounds (see
postconf -d, Postfix 2.8+) — Bit‑mask of OpenSSL bug workarounds to disable.
- tls_dane_digest_agility (on, Postfix 2.11‑3.1) — RFC 7671 DANE TLSA digest algorithm agility.
- tls_dane_trust_anchor_digest_enable (yes, Postfix 2.11‑3.1) — Enable support for DANE TLSA records with trust‑anchor digests.
- smtp_tls_trust_anchor_file (empty, Postfix 2.11+) — PEM files with trust‑anchor certificates/public keys.
- smtp_tls_force_insecure_host_tlsa_lookup (no, Postfix 2.11+) — Look up DANE TLSA even when hostname is not an alias and address records are in unsigned zone.
- tlsmgr_service_name (tlsmgr) — Name of tlsmgr service entry in master.cf.
- smtp_tls_wrappermode (no, Postfix 3.0+) — Use legacy SMTPS protocol instead of STARTTLS.
- smtp_tls_dane_insecure_mx_policy (see
postconf -d, Postfix 3.1+) — TLS policy for MX hosts with “secure” TLSA records when MX lookup was insecure.
- smtp_tls_connection_reuse (no, Postfix 3.4+) — Try multiple deliveries per TLS‑encrypted connection.
- smtp_tls_chain_files (empty, Postfix 3.4+) — List of PEM files with private keys and certificate chains.
- smtp_tls_servername (empty, Postfix 3.4+) — Server Name Indication (SNI) to send.
- tls_fast_shutdown_enable (yes, Postfix 3.5/3.4.6/3.3.5/3.2.10/3.1.13+) — Workaround for implementations that hang on TLS shutdown.
🗑️ OBSOLETE STARTTLS CONTROLS
Compatibility with Postfix < 2.3. Support will be removed in a future release.
- smtp_use_tls (no) — Opportunistic TLS.
- smtp_enforce_tls (no) — Enforcement mode.
- smtp_tls_enforce_peername (yes) — Require hostname match in certificate.
- smtp_tls_per_site (empty) — Per‑destination TLS policy.
- smtp_tls_cipherlist (empty) — Obsolete cipher list control.
⏱️ RESOURCE AND RATE CONTROLS
- smtp_connect_timeout (30s) — Time limit for TCP connection.
- smtp_helo_timeout (300s) — Time limit for HELO/EHLO and initial response.
- lmtp_lhlo_timeout (300s) — Time limit for LHLO and initial response.
- smtp_xforward_timeout (300s) — Time limit for XFORWARD command.
- smtp_mail_timeout (300s) — Time limit for MAIL FROM.
- smtp_rcpt_timeout (300s) — Time limit for RCPT TO.
- smtp_data_init_timeout (120s) — Time limit for DATA command.
- smtp_data_xfer_timeout (180s) — Time limit for sending message content.
- smtp_data_done_timeout (600s) — Time limit for sending
. and receiving response.
- smtp_quit_timeout (300s) — Time limit for QUIT command.
- smtp_mx_address_limit (5, Postfix 2.1+) — Max number of MX IP addresses to try.
- smtp_mx_session_limit (2, Postfix 2.1+) — Max number of SMTP sessions per delivery request.
- smtp_rset_timeout (20s, Postfix 2.1+) — Time limit for RSET command.
- lmtp_cache_connection (yes, Postfix 2.2‑) — Keep LMTP connections open up to $max_idle seconds.
- smtp_connection_cache_destinations (empty, Postfix 2.2+) — Permanently enable SMTP connection caching for specified destinations.
- smtp_connection_cache_on_demand (yes, Postfix 2.2+) — Temporarily enable caching when high volume.
- smtp_connection_reuse_time_limit (300s, Postfix 2.2+) — Time during which a connection can be reused.
- smtp_connection_cache_time_limit (2s, Postfix 2.2+) — Time an unused socket is kept open.
- connection_cache_protocol_timeout (5s, Postfix 2.3+) — Timeout for cache connect/send/receive.
- smtp_per_record_deadline (no, Postfix 2.9+) — Time limit per complete record.
- smtp_connection_reuse_count_limit (0, Postfix 2.11+) — Max number of times a session can be reused (0 = no limit).
- smtp_tls_connection_reuse (no, Postfix 3.4+) — Try multiple deliveries per TLS connection.
- transport_destination_concurrency_limit ($default_destination_concurrency_limit) — Transport‑specific concurrency limit (implemented in qmgr).
- transport_destination_recipient_limit ($default_destination_recipient_limit) — Transport‑specific recipient limit.
🌍 SMTPUTF8 CONTROLS
Preliminary SMTPUTF8 support introduced with Postfix 3.0.
- smtputf8_enable (yes) — Enable SMTPUTF8 support for RFC 6531‑6533.
- smtputf8_autodetect_classes (sendmail, verify) — Detect that a message requires SMTPUTF8 for specified mail origin classes.
- enable_idna2003_compatibility (no, Postfix 3.2+) — Enable transitional compatibility between IDNA2003 and IDNA2008.
🛠️ TROUBLESHOOTING CONTROLS
- debug_peer_level (2) — Increment in verbose logging level when peer matches debug_peer_list.
- debug_peer_list (empty) — List of patterns that increase verbose logging.
- error_notice_recipient (postmaster) — Recipient of postmaster notifications about policy, resource, software, or protocol errors.
- internal_mail_filter_classes (empty) — Categories of Postfix‑generated mail subject to before‑queue inspection.
- notify_classes (resource, software) — Error classes reported to postmaster.
🧩 MISCELLANEOUS CONTROLS
- best_mx_transport (empty) — Where to deliver when “mail loops back to myself” is detected.
- config_directory (see
postconf -d) — Default location of main.cf and master.cf.
- daemon_timeout (18000s) — Max time a daemon process may handle a request before watchdog termination.
- delay_logging_resolution_limit (2) — Max digits after decimal for sub‑second delay logging.
- disable_dns_lookups (no) — Disable DNS lookups in SMTP/LMTP clients.
- inet_interfaces (all) — Network interfaces to receive mail on.
- inet_protocols (see
postconf -d) — Internet protocols to use.
- ipc_timeout (3600s) — Time limit for internal communication.
- lmtp_assume_final (no) — Assume LMTP server performs final delivery if no DSN support.
- lmtp_tcp_port (24) — Default TCP port for LMTP client.
- max_idle (100s) — Max idle time before voluntary termination.
- max_use (100) — Max number of incoming connections per daemon process.
- process_id (read‑only) — Process ID of command or daemon.
- process_name (read‑only) — Process name.
- proxy_interfaces (empty) — Network addresses of proxy/NAT.
- smtp_address_preference (any) — Address type preference (ipv6, ipv4, any).
- smtp_bind_address (empty) — Numerical IPv4 address to bind to.
- smtp_bind_address6 (empty) — Numerical IPv6 address to bind to.
- smtp_helo_name ($myhostname) — Hostname sent in HELO/EHLO.
- lmtp_lhlo_name ($myhostname) — Hostname sent in LHLO.
- smtp_host_lookup (dns) — Mechanisms for host IP lookup.
- smtp_randomize_addresses (yes) — Randomize order of equal‑preference MX addresses.
- syslog_facility (mail) — Syslog facility for Postfix logging.
- syslog_name (see
postconf -d) — Prefix prepended to process name in syslog.
- fallback_relay (empty, Postfix ≤2.2) — Optional relay hosts for unreachable destinations.
- smtp_fallback_relay ($fallback_relay, Postfix 2.3+) — Relay hosts for SMTP destinations not found or unreachable.
- smtp_address_verify_target (rcpt, Postfix 3.0+) — SMTP protocol stage for address verification.
- lmtp_fallback_relay (empty, Postfix 3.1+) — Relay hosts for LMTP destinations not found or unreachable.
- smtp_tcp_port (smtp, Postfix 3.2+) — Default TCP port for SMTP client.
- service_name (read‑only, Postfix 3.3+) — master.cf service name.
📚 SEE ALSO
📄 README FILES
Use postconf readme_directory or postconf html_directory to locate this information.
- SASL_README — Postfix SASL howto
- TLS_README — Postfix STARTTLS howto
📄 LICENSE
The Secure Mailer license must be distributed with this software.
👤 AUTHOR(S)
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA
Wietse Venema
Google, Inc.
111 8th Avenue
New York, NY 10011, USA
Command pipelining in cooperation with:
Jon Ribbens
Oaktree Internet Solutions Ltd.,
Internet House,
Canal Basin,
Coventry,
CV1 4LY, United Kingdom.
SASL support originally by:
Till Franke
SuSE Rhein/Main AG
65760 Eschborn, Germany
TLS support originally by:
Lutz Jaenicke
BTU Cottbus
Allgemeine Elektrotechnik
Universitaetsplatz 3‑4
D‑03044 Cottbus, Germany
Revised TLS and SMTP connection cache support by:
Victor Duchovni
Morgan Stanley
