
Milter is a mail filter that sits in the mail server, allowing you to filter out unwanted emails before they reach your inbox. This is done by using a protocol called Sendmail's mail filter API.
Milter can be used to filter out spam emails, block specific senders, and even scan emails for viruses. It's like having a personal email bodyguard.
Milter works by intercepting emails as they pass through the mail server, giving you the opportunity to examine and modify them before they're delivered. This is a key advantage over other filtering methods that only scan emails after they've been delivered.
By using Milter, you can create custom rules to filter out emails based on specific criteria, such as sender, recipient, or message content.
Additional reading: Courier Mail Server
Milter Basics
A milter-capable MTA notifies filters about each phase of the delivery of a message, from initial client connection through completion of transmission. This allows filters to terminate acceptance of the message early when appropriate, which can have an enormous impact on large messages.
Intriguing read: Message Transfer Agent
A milter-capable MTA can connect to multiple filters in parallel, serving specific purposes such as anti-virus, anti-spam, message authentication, flow regulation, etc. This enables a more efficient and effective filtering process.
Here's a breakdown of the phases of the SMTP session where filters can intervene:
- CONNECT: Initial client connection
- DISCONNECT: Completion of transmission
- SMTP commands (HELO, MAIL FROM, etc.): Various commands sent during the SMTP session
- Mail content (headers and body): Inspection of the message content
This allows filters to take special action on the message, such as adding or removing recipients in the envelope, altering the body prior to delivery, or adding, changing, or removing header fields in the message.
History
Prior to the advent of milter, email filters were implemented as programs that analyzed the header and body of a message after it had completely arrived, making a decision to accept or reject it.
This old model had its limitations, as the filter had to wait for the entire message to arrive before making a decision, which could be inefficient, especially for very large messages.
An MTA that is milter-capable notifies filters about each phase of the delivery of a message, from initial client connection through completion of transmission.

This approach allows filters to terminate acceptance of a message early when necessary, which can have a significant impact on performance, especially for large messages.
A milter-capable MTA can connect to multiple filters in parallel that serve specific purposes, such as anti-virus, anti-spam, message authentication, and flow regulation.
The Sendmail Consortium includes a special thread-based library in the sendmail distribution that provides the milter API.
Introduction
Postfix implements support for the Sendmail version 8 Milter protocol, allowing applications to inspect SMTP events and mail content before it's queued.
The Milter protocol is used by applications that run outside the MTA to inspect SMTP events, such as CONNECT and DISCONNECT, as well as SMTP commands like HELO and MAIL FROM.
Having Milter support in Postfix makes sense, as it avoids duplicating efforts and reduces the waste of human and system resources.
There are many applications that use Milter, including OpenDKIM, which verifies authenticity and digitally signs mail, and DomainKeys Identified Mail (DKIM), which also verifies authenticity.
Recommended read: Mercury Mail Transport System
These applications can be used to block unwanted mail, verify authenticity, or digitally sign mail, making email communication more secure and trustworthy.
Some of the key topics covered in this document include how Milter applications plug into Postfix, when Postfix and Milters inspect an SMTP session, and configuring Postfix to work with Milter applications.
Here are the main topics covered in this document:
- How Milter applications plug into Postfix
- When Postfix and Milters inspect an SMTP session
- Building Milter applications
- Running Milter applications
- Configuring Postfix
- Workarounds
- Limitations
Non-SMTP
Non-SMTP mail is handled by Milter applications, which are used to digitally sign mail. These applications are typically used with the Postfix sendmail(1) command-line or the Postfix qmqpd(8) server.
Mail arriving via the Postfix smtpd(8) server is not filtered by non-SMTP filters, so it's essential to use them with the sendmail command-line or qmqpd server.
Non-SMTP filters have limitations, including the inability to filter mail arriving via the smtpd server. You should not use the header_checks(5) IGNORE action to remove Postfix's own Received: message header.
You specify non-SMTP Milter applications with the non_smtpd_milters parameter, which uses the same syntax as the smtpd_milters parameter. This parameter allows you to specify multiple Milter applications.
For more insights, see: Comparison of Mail Servers

Postfix sends commands to each Milter application in the order configured with non_smtpd_milters. If a Milter application rejects a command, it will override responses from other Milter applications.
Here's how Postfix simulates SMTP events for non-SMTP mail:
- Mail arriving via the sendmail(1) command line is simulated as arriving with ESMTP from "localhost" with IP address "127.0.0.1".
- Mail arriving via the qmqpd(8) server is simulated as arriving with ESMTP, using the QMQPD client hostname and IP address.
- Old mail re-injected into the queue with "postsuper -r" uses the same client information as when the mail arrived as new mail.
Non-SMTP filters must not REJECT or TEMPFAIL simulated RCPT TO commands, as this will cause Postfix to report a configuration error and mail will stay in the queue.
MTAs and Milter
MTAs (Mail Transfer Agents) like Sendmail and Postfix have a built-in Milter interface, which allows them to interact with external Milter applications.
Milter was first officially introduced to Sendmail 8.12.0 released on September 8, 2001. Postfix also supports Milter, and it emulates a limited number of Sendmail macros.
Postfix sends specific sets of macros at different Milter protocol stages, configured with parameters like the table below shows:
This allows Milter applications to specify what macros they want to receive at different Milter protocol stages, taking precedence over Postfix-specified lists.
MTAs
MTAs are the backbone of email systems, responsible for sending and receiving emails. Sendmail, a popular MTA, was the first to officially introduce Milter in version 8.12.0, released on September 8, 2001.
Postfix, another well-known MTA, emulates a limited number of Sendmail macros, as shown in the table below.
Postfix sends specific sets of macros at different Milter protocol stages, which are configured with parameters like milter_connect_macros, milter_helo_macros, and milter_mail_macros.
The sets of macros are available at different Milter protocol stages, such as CONNECT, HELO/EHLO, and MAIL FROM. The availability of macros is not always the same as in Sendmail, and some macro values depend on whether a recipient is rejected.
Smtp-Only
Smtp-Only Milter applications are used to filter unwanted mail and sign mail from authorized SMTP clients. They handle mail that arrives via the Postfix smtpd(8) server.
These applications are typically used to filter out unwanted mail, and they're applied in the order as specified in the smtpd_milters parameter. The first Milter application that rejects a command will override the responses from other Milter applications.
You can specify SMTP-only Milter applications with the smtpd_milters parameter, and each Milter application is identified by the name of its listening socket. This is a unique way to filter mail.
The general syntax for listening sockets is to connect to the local UNIX-domain server that is bound to the specified pathname. If the smtpd(8) or cleanup(8) process runs chrooted, an absolute pathname is interpreted relative to the Postfix queue directory.
Postfix syntax differs from Milter syntax, which has the form inet:port@host, so be aware of the difference when setting up your Milter applications.
Additional reading: Postfix (software)
Error Handling and Safety
Error handling is a crucial aspect of Milter, and understanding how it works can save you a lot of headaches down the line.
The milter_default_action parameter determines how Postfix handles Milter application errors, and the default action is to respond with a temporary error status.
Specify "accept" if you want to receive mail as if the filter does not exist, and "reject" to reject mail with a permanent status.
The "quarantine" action is like "accept" but freezes the message in the "hold" queue, and is available with Postfix 2.6 or later.
Rust callback code is safe even in the presence of panics thanks to the attribute macro-generated conversion layer.
This layer catches unwinding panics, so panicking in user code remains safe, but panic is still treated as a fatal error.
A panic triggered in a callback results in milter shutdown, which can be avoided by wrapping the callback return type in milter::Result.
Using milter::Result allows you to propagate unanticipated errors out of the callback using the ? operator, which corresponds to a Tempfail response.
You need to select the same generic type argument T when writing out the callback function arguments to avoid memory leaks in the DataHandle.
Milter Protocol and Settings
The Milter protocol is a way for Postfix to communicate with external Milter applications, and it's essential to configure the protocol version correctly. The default version is 6, but before Postfix 2.6, it's 2. If the version is too low, the libmilter library will log an error message, and you'll need to increase the version number.
Postfix uses different time limits at different Milter protocol stages. The timeout settings are as follows:
Be aware that 30s may be too short for Milter applications that do lots of DNS lookups, and increasing the timeouts too much can cause remote SMTP clients to hang up and mail to be delivered multiple times.
Interface
The Sendmail Consortium provides a documented Application Programming Interface that can be used to create milters for special needs.
The library provided by The Sendmail Consortium is pthread-based, which is a good thing if you're looking for a robust and efficient solution.
However, documentation of the protocol used for communication between sendmail and milter processes is not provided, leaving some users in the dark about how things work.
This internal protocol is subject to changes in new sendmail versions, so be prepared for some potential headaches down the line.
Different Settings
Different settings for different Milter applications are supported in Postfix 3.0 and later. This allows for more complex configurations where different settings are needed for different Milters.

Postfix uses different time limits at different Milter protocol stages, as shown in the table below:
You can override these global settings with per-Milter settings, which have the same name as the global parameters but without the "milter_" prefix.
Protocol Version
The Milter protocol version is a crucial setting in Postfix that needs to be configured correctly. The default protocol version is 6, but before Postfix 2.6, it was 2.
If you specify a too low version, the libmilter library will log an error message. The remedy is to increase the Postfix milter_protocol version number.
With Postfix 2.7 and earlier, if you specify a too high version, the libmilter library simply hangs up without logging a warning. You'll see a Postfix warning message instead.
To avoid this issue, you should lower the Postfix milter_protocol version number. Postfix 2.8 and later will automatically turn off protocol features that the application's libmilter library does not expect.
Here's a summary of the supported protocol versions and their implications:
Milter Development and Usage

Milter development is a specialized field that requires specific knowledge and tools.
Developers can create Milter filters to interact with Stalwart, which provides information about the actions Stalwart can take upon receiving instructions from a Milter filter, and the macros Stalwart uses to communicate specific session or message information to the Milter filter.
To give an idea of how to use this crate, let's create a milter that counts the envelope recipients of a message, and adds a header recording the count. This simple example demonstrates all important aspects of a milter application: handling of SMTP events with callbacks, storing data in the callback context, and finally performing some message modification operation.
Milter applications can be built in various programming languages, including C, Haskell, Java, Perl, Python, Rust, and more. For C applications, you need an object library that implements the Sendmail 8 Milter protocol, which is currently provided by Sendmail but not by Postfix.

Here are the general steps to build a Milter application in C:
- Install the Sendmail libmilter library, which may be provided by a package called "sendmail-devel" on some Linux systems.
- Build the libmilter library from Sendmail source code.
- Configure the Milter application to use the libmilter library.
- Build and install the Milter application.
Sample
A sample milter is a simple program that filters email messages. It's a great way to get started with milter development.
The milter protocol is based on a request-response model, where the milter sends a request to the sendmail program and receives a response. This allows for efficient communication between the milter and sendmail.
For example, a simple milter might use a single filter rule to block spam messages. This rule could check the sender's IP address against a list of known spammers.
Milters can also be used to perform more complex tasks, such as content filtering or virus scanning. These tasks require more sophisticated filter rules and may involve additional software components.
Development
Development can be a complex process, especially when working with Milter filters. Milter applications have been written in various programming languages, including C, Haskell, Java, Perl, Python, and Rust.

To create Milter filters, you need to understand the actions that Stalwart can take upon receiving instructions from a Milter filter. Stalwart uses macros to communicate specific session or message information to the Milter filter.
Some systems install the Sendmail libmilter library by default, while others may provide it through a package called "sendmail-devel" on Linux systems. This library is necessary for building Milter applications.
The general syntax for listening sockets is as follows, but we'll get into the specifics of building Milter applications later.
Here are the steps to build a Milter application using a pre-compiled library:
- Install the Sendmail libmilter library.
- Use the library to build applications such as OpenDKIM and OpenDMARC.
- Use the library to build other Milter applications.
Alternatively, you can build the libmilter library from Sendmail source code. This requires more effort, but gives you more control over the library.
Usage
To create a milter application, you need to define callback functions that get called as certain events happen during an SMTP conversation. These callback functions are marked up with attribute macros, such as on_rcpt, which is called for each RCPT TO command or envelope recipient.
The example demonstrates how to use the on_rcpt callback function to count the envelope recipients of a message and add a header recording the count. This involves handling of SMTP events with callbacks, storing data in the callback context, and performing some message modification operation.

A milter's behavior is implemented as callback functions that return a response Status, which determines how to proceed after completing the callback. In the example, all callbacks return Continue, meaning "proceed to the next stage".
To configure the callback functions, you need to create a Milter instance in your main function. The Milter instance serves as the entry point to configuring and running a milter application.
How Plug In
You can plug in Milter applications to Postfix using two different lists of mail filters. The SMTP-only filters handle mail that arrives via the Postfix smtpd(8) server.
To specify SMTP-only Milter applications, you need to use the smtpd_milters parameter. Mail that arrives via the Postfix smtpd(8) server is not filtered by the non-SMTP filters.
The non-SMTP filters handle mail that arrives via the Postfix sendmail(1) command-line or via the Postfix qmqpd(8) server. They are typically used to digitally sign mail only.
You can specify non-SMTP Milter applications with the non_smtpd_milters parameter. Although non-SMTP filters can be used to filter unwanted mail, they have limitations compared to the SMTP-only filters.

To connect to the specified TCP port on the specified local or remote host, you can use numeric or symbolic form. This is useful for connecting to a Milter application.
Here's a summary of how to plug in Milter applications:
How Plug Into
Milter applications can plug into Postfix in two different ways: one list of filters for SMTP mail only and one list of filters for non-SMTP mail. The two lists have different capabilities.
To specify SMTP-only Milter applications, you need to use the smtpd_milters parameter, as described in a later section. This is used to filter unwanted mail and to sign mail from authorized SMTP clients.
Mail that arrives via the Postfix smtpd(8) server is not filtered by the non-SMTP filters. These filters are typically used to digitally sign mail only and have limitations compared to the SMTP-only filters.
To specify non-SMTP Milter applications, you need to use the non_smtpd_milters parameter, as described in a later section. This is used to handle mail that arrives via the Postfix sendmail(1) command-line or via the Postfix qmqpd(8) server.
For more insights, see: List of Email Archive Software

The Postfix Milter implementation uses two different lists of mail filters, which can be seen in the figure below:
This figure shows how Milter applications plug into Postfix. Names followed by a number are Postfix commands or server programs, while unnumbered names inside shaded areas represent Postfix queues.
Milter Macros and Workarounds
Postfix emulates a limited number of Sendmail macros, which can be accessed at different Milter protocol stages. These macros include things like the queue ID, the validated client name and address, and SASL login information.
Some macros are available at all stages, while others are only available at specific stages like end-of-header (EOH) or end-of-message (EOM). For example, the "{client_addr}" macro is always available, while the "{cert_subject}" macro is only available at the HELO, MAIL, DATA, EOH, and EOM stages.
To avoid breaking DKIM signatures with an SMTP-based content filter, you can update the before-filter SMTP client in master.cf to include the line "-o disable_mime_output_conversion=yes". This will prevent the filter from converting MIME headers, which can cause the signature to break.
Options

Options play a crucial role in configuring Milter filters. The configuration options for a Milter filter can be set under the session.milter.id.options section.
You can enable temporary failure on error, which tells the sending mail server to try delivering the message again later. This is done by setting tempfail-on-error to enabled.
The maximum size of a response that Stalwart will accept from a Milter server is set by max-response-size. This value is in bytes.
Stalwart supports version 2 and 6 of the Milter protocol. You should set the version option to match the version of the Milter protocol supported by your Milter server, which is usually version 6.
Here are the configuration options for a Milter filter:
- tempfail-on-error: enables temporary failure on error
- max-response-size: sets the maximum size of a response in bytes
- version: sets the Milter protocol version (2 or 6)
- flags.actions: sets actions flags that Stalwart will advertise (defaults to 0xff)
- flags.protocol: sets protocol flags that Stalwart will advertise (defaults to 0x42)
Workarounds
If a macro value is not available at a particular Milter protocol stage, you can use workarounds to obtain the desired information. For example, if the queue ID macro is not available at the EOH stage, you can use the i macro at the DATA stage.
Some macro values depend on whether a recipient is rejected. In such cases, the Milter application can request the rejected recipient information. The rcpt_addr macro can provide the recipient address, and the rcpt_host macro can provide the recipient next-hop destination.
If you need to obtain the client name and address, you can use the _ macro. However, this macro is only available at all Milter protocol stages, so you don't need to worry about its availability.
Here's a list of macros that are available at different Milter protocol stages:
You can use the {cert_subject} macro to obtain the TLS client certificate subject, which is available at various Milter protocol stages. Similarly, the {cipher_bits} macro can provide the TLS session key size, and the {cipher} macro can provide the TLS cipher.
Milter Limitations and Troubleshooting
The Milter protocol has evolved over time, resulting in different Postfix versions implementing different feature sets.
Postfix 2.6 supports all Milter requests of Sendmail 8.14.0, while Postfix 2.5 supports all Milter requests of Sendmail 8.14.0 except for SMFIP_RCPT_REJ, SMFIR_CHGFROM, and SMFIR_ADDRCPT_PAR. Postfix 2.4 supports all Milter requests of Sendmail 8.13.0, and Postfix 2.3 supports all Milter requests of Sendmail 8.13.0 except for SMFIR_REPLBODY.
Milter applications written in C require the Sendmail libmilter library.
Postfix has two sets of mail filters: filters for SMTP mail only, specified with the smtpd_milters parameter, and filters for non-SMTP mail, specified with the non_smtpd_milters parameter.
Here's a summary of supported Milter requests by Postfix version:
Postfix 2.6 ignores optional ESMTP parameters in requests to replace the sender or append a recipient, and logs a warning message when a Milter application supplies such parameters.
Milter applications have access only to SMTP command information when using the before-queue content filter for incoming SMTP mail, and cannot make modifications to the message or envelope.
Postfix 2.3 does not implement requests to replace the message body, and Milter applications log a warning message when they need this unsupported operation.
Milter Installation and Running
To run a Milter application, you'll need to see the documentation of the filter for options. A typical command looks like this:
Please specify a userid value that isn't used for other applications (not "postfix", not "www", etc.). It's essential to choose a unique userid to avoid conflicts with other applications.
Running a Milter application requires some configuration, and the documentation of the filter will provide you with the necessary information. The typical command structure is crucial to get it right.
You'll need to follow the specific instructions provided in the filter's documentation to set up the Milter application correctly. This may involve specifying additional options or parameters.
Frequently Asked Questions
What is the milter server in Zimbra?
The Zimbra milter server is a feature that regulates who can send emails from distribution lists. It only allows users with explicit sending permissions to send emails when enabled.
Featured Images: pexels.com

