The Mail Filter (milter) Protocol

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 29 April 2027.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

Milter (a portmanteau of "mail filter") was officially introduced into open source Sendmail 8.12.0 released on September 8, 2001. It provided a plugin architecture by which a Mail Transfer Agent (MTA) can communicate with an arbitrary number of local filtering agents to observe and possibly modify messages in transit or influence their delivery. Filters implementing the milter protocol (called "milters") are optionally involved at each phase of an SMTP [RFC5321] transaction.¶

Milter is also supported by Postfix, which together with Sendmail provides milter capabilities to the bulk of open source MTA deployment worldwide.¶

2. Conventions and Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

MTA:

The Mail Transfer Agent; the client of this protocol.¶

Filter (or milter):

The server of this protocol.¶

Octet:

An 8-bit byte.¶

Network byte order:

Big-endian, most significant octet first.¶

Null-terminated string:

A sequence of zero or more non-NUL octets followed by one octet of value 0x00. Unless stated otherwise, such strings are US-ASCII.¶

Numeric constants are given in hexadecimal with a "0x" prefix. Command and response identifiers are single US-ASCII characters and are shown in single quotes; the quotes are not part of the protocol.¶

3. Protocol Model

The milter protocol is a connection-oriented, binary, largely half-duplex request/response protocol. The MTA connects to the filter and drives the exchange; the filter reacts. There is no filter-initiated request other than responses.¶

  MTA                                     Filter
   |--- 'O' OPTNEG ----------------------->|
   |<-- 'O' OPTNEG (agreed) --------------|
   |--- 'D' MACRO(for 'C') --------------->|   (optional, no reply)
   |--- 'C' CONNECT ---------------------->|
   |<-- 'c' CONTINUE ---------------------|
   |--- 'H' HELO ------------------------->|
   |<-- 'c' CONTINUE ---------------------|
   |--- 'M' MAIL ------------------------->|
   |<-- 'c' CONTINUE ---------------------|
   |--- 'R' RCPT ------------------------->|   (once per recipient)
   |<-- 'c' CONTINUE ---------------------|
   |--- 'T' DATA ------------------------->|
   |<-- 'c' CONTINUE ---------------------|
   |--- 'L' HEADER ----------------------->|   (once per header field)
   |<-- 'c' CONTINUE ---------------------|
   |--- 'N' EOH -------------------------->|
   |<-- 'c' CONTINUE ---------------------|
   |--- 'B' BODY ------------------------->|   (repeated)
   |<-- 'c' CONTINUE  or  'S' SKIP -------|
   |--- 'E' BODYEOB ---------------------->|
   |<-- zero or more modification actions -|
   |<-- final disposition ----------------|
   |--- 'A' ABORT / 'Q' QUIT / 'K' QUIT_NC >|

4. Packet Framing

All protocol data units ("packets") share one framing:¶

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |                          len (uint32)                         |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |    cmd/resp   |                                               |
  +-+-+-+-+-+-+-+-+          data (len - 1 octets)                +
  |                             ...                               |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

len:

Unsigned 32-bit integer in network byte order, giving the number of octets that follow, i.e. one octet of command/response identifier plus the length of the data. The value MUST be at least 1. The length field itself is not counted.¶

cmd/resp:

One octet identifying the command (Section 6) or response (Section 7).¶

data:

Exactly len-1 octets, whose interpretation depends on the identifier. Where a field is a null-terminated string, the terminating NUL is included in len.¶

A receiver MUST impose an upper bound on len and MUST close the connection rather than attempt to buffer an implausibly large packet. Implementations commonly bound the negotiated maximum body chunk (Section 5.3) and reject packets exceeding it. A receiver MUST treat an unknown identifier, a truncated packet, a missing NUL terminator, or a data length inconsistent with the identifier's definition as a protocol error and close the connection.¶

Multiple packets MAY be coalesced into a single transport write; receivers MUST NOT rely on message boundaries in the transport stream.¶

5. Option Negotiation

Immediately after the connection is established, the MTA MUST send SMFIC_OPTNEG ('O') and the filter MUST reply with SMFIC_OPTNEG ('O'). No other command may precede this exchange.¶

  'O'  version   (uint32)   protocol version, 6 for this specification
       actions   (uint32)   bitmask of SMFIF_* (Section 5.2)
       protocol  (uint32)   bitmask of SMFIP_* (Section 5.3)

In the MTA's offer, "actions" and "protocol" advertise everything the MTA is able to support. In the filter's reply, the filter MUST NOT set any bit the MTA did not offer; the reply bits are the operative agreement for the remainder of the connection. The filter MUST request in "actions" every modification it may later attempt, and MUST set in "protocol" the bits describing the commands it wishes to be spared and the replies it will omit. An MTA that receives a version it does not support, or a bit it did not offer, MUST close the connection.¶

The filter's reply MAY be followed by zero or more macro list entries, permitted only if SMFIF_SETSYMLIST was negotiated:¶

       stage     (uint32)   0=connect 1=helo 2=mail 3=rcpt
                            4=data 5=eom 6=eoh
       macros    (string)   space-separated macro names, NUL-terminated

Each entry replaces the MTA's default macro set for that stage. A stage MUST NOT appear more than once.¶

6. Commands (MTA to Filter)

Unless a no-reply or suppression bit was negotiated, the MTA MUST wait for a response to each command before sending the next, and the filter MUST send exactly one terminal response per command.¶

  'D'  cmdcode   (char)     command letter these macros apply to
       pairs      ...       name NUL value NUL, repeated to end of packet

  'C'  hostname  (string)   validated client name, or bracketed address
       family    (char)     'U' unknown, 'L' unix, '4' inet, '6' inet6
       port      (uint16)   client source port, present unless family 'U'
       address   (string)   textual address, present unless family 'U'

  'H'  helo      (string)   argument of the HELO or EHLO command

  'M'  args       ...       one or more NUL-terminated strings

  'R'  args       ...       one or more NUL-terminated strings

  'T'  (no data)

  'L'  name      (string)   header field name, without the colon
       value     (string)   header field value

  'N'  (no data)

  'B'  chunk      ...       opaque body octets, not NUL-terminated

  'E'  (no data)

  'U'  command   (string)   the unrecognized SMTP command text

  'A'  (no data)

  'Q'  (no data)     close the milter connection
  'K'  (no data)     close the SMTP connection context; reuse this one

7. Responses (Filter to MTA)

Responses fall into three classes: terminal dispositions, which conclude the handling of a command; non-terminal responses, which do not conclude it; and modification actions, valid only at end of message and always followed by a terminal disposition.¶

  'y'  reply     (string)   "NNN[ ENH.S.C] text", NUL-terminated

  'p'  (no data)

  'S'  (no data)

  'h'  name      (string)   append a header field
       value     (string)
  ---
  'i'  index     (uint32)   insert a header field; 1 = before the first
       name      (string)   existing field, 0 is treated as 1; an index
       value     (string)   past the end appends
  ---
  'm'  index     (uint32)   1-based occurrence of this field name to
       name      (string)   change; empty value deletes the field
       value     (string)
  ---
  'b'  data       ...       replacement body octets, not NUL-terminated
  ---
  '+'  rcpt      (string)   add envelope recipient
  ---
  '2'  rcpt      (string)   add envelope recipient with ESMTP parameters
       args      (string)
  ---
  '-'  rcpt      (string)   delete envelope recipient
  ---
  'e'  from      (string)   replace envelope sender
       args      (string)   optional ESMTP parameters; may be absent
  ---
  'q'  reason    (string)   quarantine; empty reason releases

8. Macros

Macros are name/value pairs supplied through SMFIC_MACRO (Section 6) and give the filter access to MTA state not otherwise carried on the wire. Availability is MTA-specific and, when SMFIF_SETSYMLIST is negotiated, configurable per stage. A filter MUST tolerate the absence of any macro. The following are widely implemented.¶

9. Error Handling and Timeouts

The protocol carries no error response. Any framing violation, unexpected or out-of-sequence identifier, or action that was not negotiated is a protocol error, and the detecting party MUST close the connection without further exchange.¶

An MTA MUST apply a timeout to each response and SHOULD apply separate timeouts to connection establishment, to sending, and to end-of-message processing. SMFIR_PROGRESS restarts the response timer. On timeout, or on any failure to connect to or communicate with a filter, the MTA MUST apply a locally configured default action; a temporary rejection is RECOMMENDED as it is fail-closed without permanently losing mail.¶

Where an MTA consults several filters, it does so in a configured order, passing each stage through the filters in turn; the first non-continue disposition terminates consideration of that stage, and modifications made by one filter are visible to those following it.¶

10. IANA Considerations

This document specifies no actions for IANA.¶

11. Security Considerations

The protocol provides no authentication, integrity protection, or confidentiality. A milter connection can carry the full content of every message, including credentials asserted through macros, in cleartext, and a filter can reject, discard, or rewrite any message. Deployments MUST therefore confine milter traffic to a trusted path — a local socket with restrictive permissions, a loopback interface, or a channel protected by TLS [RFC8446] or an equivalent — and MTAs MUST NOT accept filter connections from, nor connect to filters at, unauthenticated network locations.¶

Further considerations: length fields are attacker-influenced and invite memory exhaustion if not bounded; a slow or wedged filter is a denial-of-service vector against the MTA, and the fail-open default action is a filtering-bypass vector; header and body modifications can invalidate signatures such as DKIM [RFC6376]; filter-supplied reply text is echoed to untrusted clients and can leak internal detail or be used for injection if not sanitized.¶

Acknowledgments

[[TODO]]¶

Authors' Addresses