5.11 Header Modification Functions

There are two ways to modify message headers in a MFL script. First is to use header actions, described in Actions, and the second way is to use message modification functions. Compared with the actions, the functions offer a series of advantages. For example, using functions you can construct the name of the header to operate upon (e.g. by concatenating several arguments), something which is impossible when using actions. Moreover, apart from three basic operations (add, modify and remove), as supported by header actions, header functions allow to insert a new header into a particular place.

Built-in Function: void header_add (string name, string value)

Adds a header ‘name: value’ to the message.

In contrast to the add action, this function allows to construct the header name using arbitrary MFL expressions.

Built-in Function: void header_add (string name, string value, number idx)

This syntax is preserved for backward compatibility. It is equivalent to header_insert, which see.

Built-in Function: void header_insert (string name, string value, number idx)

This function inserts a header ‘name: ‘value’’ at idxth header position in the internal list of headers maintained by the MTA. That list contains headers added to the message either by the filter or by the MTA itself, but not the headers included in the message itself. Some of the headers in this list are conditional, e.g. the ones added by the ‘H?cond?’ directive in sendmail.cf. MTA evaluates them after all header modifications have been done and removes those of headers for which they yield false. This means that the position at which the header added by header_insert will appear in the final message will differ from idx.

Built-in Function: void header_delete (string name [, number index])

Delete header name from the envelope. If index is given, delete indexth instance of the header name.

Notice the differences between this function and the delete action:

1. It allows to construct the header name, whereas delete requires it to be a literal string.
2. Optional index argument allows to select a particular header instance to delete.

Built-in Function: void header_replace (string name, string value [, number index])

Replace the value of the header name with value. If index is given, replace indexth instance of header name.

Notice the differences between this function and the replace action:

1. It allows to construct the header name, whereas replace requires it to be a literal string.
2. Optional index argument allows to select a particular header instance to replace.

Library Function: void header_rename (string name, string newname[, number idx])

Defined in the module header_rename.mfl.
Available only in the ‘eom’ handler.

Renames the idxth instance of header name to newname. If idx is not given, assumes 1.

If the specified header or the idx instance of it is not present in the current message, the function silently returns. All other errors cause run-time exception.

The position of the renamed header in the header list is not preserved.

The example below renames ‘Subject’ header to ‘X-Old-Subject’:

require 'header_rename'

prog eom
do
  header_rename("Subject", "X-Old-Subject")
done

Library Function: void header_prefix_all (string name [, string prefix])

Defined in the module header_rename.mfl.
Available only in the ‘eom’ handler.

Renames all headers named name by prefixing them with prefix. If prefix is not supplied, removes all such headers.

All renamed headers will be placed in a continuous block in the header list. The absolute position in the header list will change. Relative ordering of renamed headers will be preserved.

Library Function: void header_prefix_pattern (string pattern, string prefix)

Defined in the module header_rename.mfl.
Available only in the ‘eom’ handler.

Renames all headers with names matching pattern (in the sense of fnmatch, see fnmatches) by prefixing them with prefix.

All renamed headers will be placed in a continuous block in the header list. The absolute position in the header list will change. Relative ordering of renamed headers will be preserved.

If called with one argument, removes all headers matching pattern.

For example, to prefix all headers beginning with ‘X-Spamd-’ with an additional ‘X-’:

require 'header_rename'

prog eom
do
  header_prefix_pattern("X-Spamd-*", "X-")
done