Recipient domain matches	Recipient lookup table
$mydestination or $inet_interfaces	$local_recipient_maps
$virtual_alias_domains	$virtual_alias_maps
$virtual_mailbox_domains	$virtual_mailbox_maps
$relay_domains	$relay_recipient_maps

Postfix Configuration - UCE Controls

Note: this web page is no longer maintained. It exists only to avoid breaking links in web pages that describe earlier versions of the Postfix mail system.

Introduction

Postfix offers a variety of parameters that limit the delivery of unsolicited commercial email (UCE).

By default, the Postfix SMTP server will accept mail only from or to the local network or domain, or to domains that are hosted by Postfix, so that your system can't be used as a mail relay to forward bulk mail from random strangers.

The text in this document describes how you can set up more detailed anti-UCE policies that prevent delivery of unwanted email altogether, for example with sendmail-style access lists or with RBL (real-time blackhole list) name servers.

Unless indicated otherwise, all parameters described here are in the main.cf file. If you change parameters of a running Postfix system, don't forget to issue a postfix reload command.

Header filtering
Body filtering
Client hostname/address restrictions
Require HELO (EHLO) command
HELO (EHLO) hostname restrictions
Require strict RFC 821-style envelope addresses
Sender address restrictions
Recipient address restrictions
ETRN command restrictions
Generic restrictions
Additional UCE control parameters

Header filtering

The header_checks parameter restricts what is allowed in message headers. Patterns are applied to entire logical message headers, even when a header spans multiple lines of text.

By default, the same header_checks patterns are used for primary message headers, for MIME headers (including headers at the start of multipart body parts), and for the headers at the beginning of attached email messages.

Default:: Allow anything in message headers.
Syntax:

Examples (main.cf):

header_checks = regexp:/etc/postfix/header_checks

header_checks = pcre:/etc/postfix/header_checks

Example (header_checks):

/^to: *friend@public\.com$/ REJECT

Body filtering

The body_checks parameter restricts what text is is allowed in message body lines.

Note: the message body is matched one line at a time. There is no multi-line concept as with message headers.

Default:: Allow anything in message body lines.
Syntax:

Examples (main.cf):

body_checks = regexp:/etc/postfix/body_checks

body_checks = pcre:/etc/postfix/body_checks

Client hostname/address restrictions

The smtpd_client_restrictions parameter restricts what clients this system accepts SMTP connections from.

By default, this restriction is applied when the client sends the RCPT TO command. In order to have the restriction take effect as soon as possible, specify smtpd_delay_reject = no in the Postfix main.cf configuration file. Doing so may cause unexpected results with poorly implemented client software.

Default:: smtpd_client_restrictions =; Allow SMTP connections from any client.
Syntax:

Require HELO (EHLO) command

The smtpd_helo_required parameter determines if clients must send a HELO (or EHLO) command at the beginning of an SMTP session. Requiring this will stop some UCE software.

Default:: smtpd_helo_required = no

HELO (EHLO) hostname restrictions

The smtpd_helo_restrictions parameter restricts what hostnames clients may send with the HELO (EHLO) command. Some UCE software can be stopped by being strict here.

Default:: smtpd_helo_restrictions =

Require strict RFC 821-style envelope addresses

The strict_rfc821_envelopes parameter controls how tolerant Postfix is with respect to addresses given in MAIL FROM or RCPT TO commands. Unfortunately, the widely-used Sendmail program tolerates lots of non-standard behavior, so a lot of software expects to get away with it. Being strict to the RFC not only stops unwanted mail, it also blocks legitimate mail from poorly-written mail applications.

Default:: strict_rfc821_envelopes = no

Sender address restrictions

The smtpd_sender_restrictions parameter restricts what sender addresses this system accepts in MAIL FROM commands.

Default:: smtpd_sender_restrictions =

Recipient address restrictions

The smtpd_recipient_restrictions parameter restricts what recipient addresses this system accepts in RCPT TO commands.

Default:: smtpd_recipient_restrictions = permit_mynetworks, reject_unauth_destination

ETRN command restrictions

Not really an UCE restriction, the smtpd_etrn_restrictions parameter restricts what domains can be specified in ETRN commands, and what clients can issue ETRN commands.

Default:: smtpd_etrn_restrictions =

Generic restrictions

The following restrictions can use used for client hostnames or addresses, for HELO (EHLO) hostnames, for sender mail addresses and for recipient mail addresses.

Restrictions:

permit: Permit the request. This restriction is useful at the end of a restriction list, to make the default policy explicit.
defer: Defer the request. The client is told to try again later. This restriction is useful at the end of a restriction list, to make the default policy explicit.
reject: Reject the request. This restriction is useful at the end of a restriction list, to make the default policy explicit. The reject_code configuration parameter specifies the response code to rejected requests (default: 554).
warn_if_reject: Change the meaning of the next restriction, so that it logs a warning instead of rejecting a request (look for logfile records that contain "reject_warning"). This is useful for testing new restrictions in a "live" environment without risking unnecessary loss of mail.
reject_unauth_pipelining: Reject the request when the client sends SMTP commands ahead of time without knowing that Postfix actually supports SMTP command pipelining. This stops mail from bulk mail software that improperly uses SMTP command pipelining to speed up deliveries.

Additional UCE control parameters

default_rbl_reply: The default reply template that is used when an SMTP client request is blocked by a reject_rbl or reject_rhsbl restriction. The reply template is subjected to exactly one level of $name macro substitution as described below. The smtpd_expansion_filter configuration parameter specifies the set of characters that are allowed in $name macro expansions. Characters outside the allowed set are replaced by "_".

Default:
default_rbl_reply = $rbl_code Service unavailable; $rbl_class [$rbl_what] blocked using $rbl_domain${rbl_reason?; $rbl_reason}
Instead of the form $name you can also specify ${name} or $(name).

Macro expansion syntax:

$client
The client hostname and IP address, formatted as name[address].
$client_name
The client hostname, or unknown.
$client_address
The client IP address.
$helo_name
The hostname given in the HELO or EHLO command, or the empty string when no HELO or EHLO command was given.
$sender
The sender address, or <> in case of the null address.
$sender_name
The sender address localpart, or <> in case of the null address.
$sender_domain
The sender address domain, or the empty string when no domain is available.
$recipient
The recipient address, or <> in case of the null address.
$recipient_name
The recipient address localpart, or <> in case of the null address.
$recipient_domain
The recipient address domain, or the empty string when no domain is available.
$rbl_what
The blacklisted entity: an IP address, a hostname, a domain name, or an email address whose domain is blacklisted.
$rbl_domain
The RBL domain where $rbl_what is blacklisted with an A record.
$rbl_reason
The reason why $rbl_what is blacklisted, or the empty string when no information is available.
$rbl_class
The blacklisted entity type: Client host, Helo command, Sender address, or Recipient address.
$rbl_code
The numerical server reply code, as specified with the maps_rbl_reject_code configuration parameter (default: 554).
All other text
Copied without change, with the exception of conditional macro expansion as described below.

Conditional macro expansion syntax:

${name?text}
expands to text if $name is not empty.
${name:text}
expands to text if $name is empty.

permit_mx_backup_networks

Restrict the use of the permit_mx_backup relay control feature to destinations whose primary MX hosts match a list of network blocks.

Default:

permit_mx_backup_networks =

That is, all networks are authorized by default.

Syntax:

Specify a list of network blocks in CIDR (network/mask) notation, for example:

permit_mx_backup_networks = 168.100.0.0/16

You can also specify the absolute pathname of a pattern file instead of listing the patterns in the main.cf file.

rbl_reply_maps

This parameter specifies lookup tables with RBL reply templates indexed by RBL domain name. If no template is found, the default_rbl_reply template is used instead.

Default:

rbl_reply_maps =

By default, Postfix always uses the default_rbl_reply template.

Syntax:

Specify zero or more type:name lookup tables, separated by whitespace and/or commas. For the syntax of the template reply strings, see the default_rbl_reply parameter description.

relay_domains

This parameter controls the behavior of the reject_unauth_destination and permit_auth_destination restrictions that can appear as part of a recipient address restriction list.

Default:

relay_domains = $mydestination

By default, the Postfix SMTP server relays mail:

from trusted clients whose IP address matches $mynetworks,
from untrusted clients to destinations that match $relay_domains or a subdomain thereof, except for addresses that contain sender-specified routing (user@elsewhere@domain).

Syntax:

Specify zero or more domain names, /file/name patterns and/or type:name lookup tables, separated by whitespace and/or commas. A /file/name is replaced by its contents; type:name requests that table lookup is done instead of string comparison.

A host or destination address matches $relay_domains when its name or parent domain matches any of the names, files or lookup tables listed in $relay_domains.

smtpd_sender_login_maps

This parameter specifies ownership of MAIL FROM addresses, as used by the reject_sender_login_mismatch sender address restriction.

Default:

smtpd_sender_login_maps =

Syntax:

Specify zero or more type:name lookup tables, separated by whitespace and/or commas. The maps are searched in the specified order. Regexp tables are allowed.

Each map entry specifies a sender address and the login name that owns the address. The search order is:

user@domain owner: This form has the highest precedence.
user owner: This matches user@site when site is equal to $myorigin, when site is listed in $mydestination, or when it is listed in $inet_interfaces.
@domain owner: This matches every address in the specified domain, and has the lowest precedence.