Exim Filter Specification section 16

Previous Next Contents (Exim Filter Specification)

## 16. Mail commands

There are two commands which cause the creation of a new mail message, neither of which count as a significant delivery unless the command is preceded by the word `seen`. This is a powerful facility, but it should be used with care, because of the danger of creating infinite sequences of messages. The system administrator can forbid the use of these commands altogether.

To help prevent runaway message sequences, these commands have no effect when the incoming message is a delivery error message, and messages sent by this means are treated as if they were reporting delivery errors. Thus they should never themselves cause a delivery error message to be returned. The basic mail-sending command is

`` `mail [to <address-list>]`
`` `[cc <address-list>]`
`` `[bcc <address-list>]`
`` `[from <address>]`
`` `[reply_to <address>]`
`` `[subject <text>]`
`` `[text <text>]`
`` `[[expand] file <filename>]`
`` `[return message]`
`` `[log <log file name>]`
`` `[once <note file name>]`
`` `[once_repeat <time interval>]`
`` `e.g. mail text "Your message about $h_subject: has been received"`

As a convenience for use in one common case, there is also a command called `vacation`. It behaves in the same way as `mail`, except that the defaults for the `file`, `log`, `once`, and `once_repeat` options are

`` `expand file .vacation.msg`
`` `log .vacation.log`
`` `once .vacation`
`` `once_repeat 7d`

respectively. These are the same file names and repeat period used by the traditional Unix `vacation` command. The defaults can be overridden by explicit settings, but if a file name is given its contents are expanded only if explicitly requested. The `vacation` command is normally used conditionally, subject to the `personal` condition (see section 25 below) so as not to send automatic replies to non-personal messages from mailing lists or elsewhere.

For both commands, the key/value argument pairs can appear in any order. At least one of `text` or `file` must appear (except with `vacation`); if both are present, the text string appears first in the message. If `expand` precedes `file`, each line of the file is subject to string expansion as it is included in the message.

Several lines of text can be supplied to `text` by including the escape sequence ``\n'' in the string where newlines are required. If the command is output during filter file testing, newlines in the text are shown as ``\n''.

Note that the keyword for creating a `Reply-To:` header is `reply_to`, because Exim keywords may contain underscores, but not hyphens. If the `from` keyword is present and the given address does not match the user who owns the forward file, Exim normally adds a `Sender:` header to the message, though it can be configured not to do this.

If no `to` argument appears, the message is sent to the address in the `$reply_address` variable (see section 6 above). An `In-Reply-To:` header is automatically included in the created message, giving a reference to the message identification of the incoming message.

If `return message` is specified, the incoming message that caused the filter file to be run is added to the end of the message, subject to a maximum size limitation.

If a log file is specified, a line is added to it for each message sent.

If a `once` file is specified, it is used to hold a database for remembering who has received a message, and no more than one message is ever sent to any particular address, unless `once_repeat` is set. This specifies a time interval after which another copy of the message is sent. The interval is specified as a sequence of numbers, each followed by the initial letter of one of ``seconds'', ``minutes'', ``hours'', ``days'', or ``weeks''. For example,

      once_repeat 5d4h

causes a new message to be sent if 5 days and 4 hours have elapsed since the last one was sent. There must be no white space in a time interval.

Commonly, the file name specified for `once` is used as the base name for direct-access (DBM) file operations. There are a number of different DBM libraries in existence. Some operating systems provide one as a default, but even in this case a different one may have been used when building Exim. With some DBM libraries, specifying `once` results in two files being created, with the suffixes `.dir` and `.pag` being added to the given name. With some others a single file with the suffix `.db` is used, or the name is used unchanged.

Using a DBM file for implementing the `once` feature means that the file grows as large as necessary. This is not usually a problem, but some system administrators want to put a limit on it. The facility can be configured not to use a DBM file, but instead, to use a regular file with a maximum size. The data in such a file is searched sequentially, and if the file fills up, the oldest entry is deleted to make way for a new one. This means that some correspondents may receive a second copy of the message after an unpredictable interval. Consult your local information to see if your system is configured this way.

More than one `mail` or `vacation` command may be obeyed in a single filter run; they are all honoured, even when they are to the same recipient.

Previous Next Contents (Exim Filter Specification)