5.13 Message Modification Queue

Message modification functions described in the previous subsections do not take effect immediately, in the moment they are called. Instead they store the requested changes in the internal message modification queue. These changes are applied at the end of processing, before ‘eom’ stage finishes (see Figure 3.1).

One important consequence of this way of operation is that calling any MTA action (see Actions), causes all prior modifications to the message to be ignored. That is because after receiving the action command, MTA will not call filter for that message any more. In particular, the ‘eom’ handler will not be called, and the message modification queue will not be flushed. While it is logical for such actions as reject or tempfail, it may be quite confusing for accept. Consider, for example, the following code:

prog envfrom
do
  if $1 == ""
    header_add("X-Filter", "foo")
    accept
  fi
done

Obviously, the intention was to add a ‘X-Filter’ header and accept the message if it was sent from the null address. What happens in reality, however, is a bit different: the message is accepted, but no header is added to it. If you need to accept the message and retain any modifications you have done to it, you need to use an auxiliary variable, e.g.:

number accepted 0
prog envfrom
do
  if $1 == ""
    header_add("X-Filter", "foo")
    set accepted 1
  fi
done

Then, test this variable for non-zero value at the beginning of each subsequent handler, e.g.:

prog data
do
  if accepted
    continue
  fi
  ...
done

To help you trace such problematic usages of accept, mailfromd emits the following warning:

RUNTIME WARNING near /etc/mailfromd.mfl:36: `accept' causes previous
message modification commands to be ignored; call mmq_purge() prior
to `accept', to suppress this warning

If it is OK to lose all modifications, call mmq_purge, as suggested in this message.

Built-in Function: void mmq_purge ()

Remove all modification requests from the queue. This function undoes the effect of any of the following functions, if they had been called previously: rcpt_add, rcpt_delete, header_add, header_insert, header_delete, header_replace, replbody, quarantine.