3.1 Start Up

The mailfromd utility runs as a standalone daemon program and listens on a predefined communication channel for requests from the Mail Transfer Agent (MTA, for short). When processing each message, the MTA installs communication with mailfromd, and goes through several states, collecting the necessary data from the sender. At each state it sends the relevant information to mailfromd, and waits for it to reply. The mailfromd filter receives the message data through Sendmail macros and runs a handler program defined for the given state. The result of this run is a response code, that it returns to the MTA. The following response codes are defined:

continue

Continue message processing from next milter state.

accept

Accept this message for delivery. After receiving this code the MTA continues processing this message without further consulting mailfromd filter.

reject

Reject this message. The message processing stops at this stage, and the sender receives the reject reply (‘5xx’ reply code). No further mailfromd handlers are called for this message.

discard

Silently discard the message. This means that MTA will continue processing this message as if it were going to deliver it, but will discard it after receiving. No further interaction with mailfromd occurs.

tempfail

Temporarily reject the message. The message processing stops at this stage, and the sender receives the ‘temporary failure’ reply (‘4xx’ reply code). No further mailfromd handlers are called for this message.

The instructions on how to process the message are supplied to mailfromd in its filter script file. It is normally called /usr/local/etc/mailfromd.mfl (but can be located elsewhere, see Invocation) and contains a set of milter state handlers, or subroutines to be executed in various SMTP states. Each interaction state can be supplied its own handling procedure. A missing procedure implies continue response code.

The filter script can define up to nine milter state handlers, called after the names of milter states: ‘connect’, ‘helo’, ‘envfrom’, ‘envrcpt’, ‘data’, ‘header’, ‘eoh’, ‘body’, and ‘eom’. The ‘data’ handler is invoked only if MTA uses Milter protocol version 3 or later. Two special handlers are available for initialization and clean-up purposes: ‘begin’ is called before the processing starts, and ‘end’ is called after it is finished. The diagram below shows the control flow when processing an SMTP transaction. Lines marked with C: show SMTP commands issued by the remote machine (the client), those marked with ‘⇒’ show called handlers with their arguments. An ‘[R]’ appearing at the start of a line indicates that this part of the transaction can be repeated any number of times:

⇒ begin()
⇒ connect(hostname, family, port, ‘IP address’)
C: HELO domain
helo(domain)
for each message transaction
do
        C: MAIL FROM sender
        ⇒ envfrom(sender)

[R]     C: RCPT TO recipient
        ⇒ envrcpt(recipient)

        C: DATA
        ⇒ data()
[R]     C: header: value
        ⇒ header(header, value)

        C:
        ⇒ eoh()

[R]     C: body-line
        ⇒ /* Collect lines into blocks blk of
        ⇒  * at most len bytes and for each
        ⇒  * such block call:
        ⇒  */
        ⇒ body(blk, len)

        C: .
        ⇒ eom()
done
⇒ end()

This control flow is maintained for as long as each called handler returns continue (see Actions). Otherwise, if any handler returns accept or discard, the message processing continues, but no other handler is called. In the case of accept, the MTA will accept the message for delivery, in the case of discard it will silently discard it.

If any of the handlers returns reject or tempfail, the result depends on the handler. If this code is returned by envrcpt handler, it causes this particular recipient address to be rejected. When returned by any other handler, it causes the whole message will be rejected.

The reject and tempfail actions executed by helo handler do not take effect immediately. Instead, their action is deferred until the next SMTP command from the client, which is usually MAIL FROM.