Exim Filter Specification - Expansion variables

Go to the first, previous, next, last section, table of contents.

## Expansion variables

This list of expansion variable substitutions contains those that are likely to be of use in filter files. Others that are not relevant at filtering time, or are of interest only to the system administrator, are omitted.

$0, $1, etc: When a matches expansion condition succeeds, these variables contain the captured substrings identified by the regular expression during subsequent processing of the success string of the containing if expansion item. They may also be set externally by some other matching process which precedes the expansion of the string. For example, the commands available in Exim filter files include an if command with its own regular expression matching condition.

$body_linecount: When a message is being received or delivered, this variable contains the number of lines in the message's body.

$caller_gid: The group id under which the process that called Exim was running. This is not the same as the group id of the originator of a message (see $originator_gid). If Exim re-execs itself, this variable in the new incarnation normally contains the Exim gid.

$caller_uid: The user id under which the process that called Exim was running. This is not the same as the user id of the originator of a message (see $originator_uid). If Exim re-execs itself, this variable in the new incarnation normally contains the Exim uid.

$compile_date: The date on which the Exim binary was compiled.

$compile_number: The building process for Exim keeps a count of the number of times it has been compiled. This serves to distinguish different compilations of the same version of the program.

$domain: When an address is being directed, routed, or delivered on its own, this variable contains the domain. In particular, it is set during user filtering, but not during system filtering, since a message may have many recipients and the system filter is called just once.

$home: This is set to the user's home directory when user filtering is configured in the normal way. When running a filter test via the -bf option, $home is set to the value of the environment variable HOME.

$local_part: When an address is being directed, routed, or delivered on its own, this variable contains the local part. If a local part prefix or suffix has been recognized, it is not included in the value.

$local_part_prefix: When an address is being directed or delivered locally, and a specific prefix for the local part was recognized, it is available in this variable. Otherwise it is empty.

$local_part_suffix: When an address is being directed or delivered locally, and a specific suffix for the local part was recognized, it is available in this variable. Otherwise it is empty.

$message_body: This variable contains the initial portion of a message's body while it is being delivered, and is intended mainly for use in filter files. The maximum number of characters of the body that are used is set by the message_body_visible configuration option; the default is 500. Newlines are converted into spaces to make it easier to search for phrases that might be split over a line break.

$message_body_end: This variable contains the final portion of a message's body while it is being delivered. The format and maximum size are as for $message_body.

$message_body_size: When a message is being received or delivered, this variable contains the size of the body in bytes. The count starts from the character after the blank line that separates the body from the header. Newlines are included in the count. See also $message_size and $body_linecount.

$message_headers: This variable contains a concatenation of all the header lines when a message is being processed. They are separated by newline characters.

$message_id: When a message is being received or delivered, this variable contains the unique message id which is used by Exim to identify the message.

$message_precedence: When a message is being delivered, the value of any Precedence: header is made available in this variable. If there is no such header, the value is the null string.

$message_size: When a message is being received or delivered, this variable contains its size in bytes. In most cases, the size includes those headers that were received with the message, but not those (such as Envelope-to:) that are added to individual deliveries as they are written. See also $message_body_size and $body_linecount.

$n0 -- $n9: These variables are counters that can be incremented by means of the add command in filter files.

$original_domain: When a top-level address is being processed for delivery, this contains the same value as $domain. However, if a `child' address (for example, generated by an alias, forward, or filter file) is being processed, this variable contains the domain of the original address. This differs from $parent_domain when there is more than one level of aliasing or forwarding.

$original_local_part: When a top-level address is being processed for delivery, this contains the same value as $local_part. However, if a `child' address (for example, generated by an alias, forward, or filter file) is being processed, this variable contains the local part of the original address. This differs from $parent_local_part when there is more than one level of aliasing or forwarding.

$originator_gid: The value of $caller_gid that was set when the message was received. For messages received via the command line, this is the gid of the sending user. For messages received by SMTP over TCP/IP, this is normally the gid of the Exim user.

$originator_uid: The value of $caller_uid that was set when the message was received. For messages received via the command line, this is the uid of the sending user. For messages received by SMTP over TCP/IP, this is normally the uid of the Exim user.

$parent_domain: This variable is empty, except when a `child' address (generated by aliasing or forwarding, for example) is being processed, in which case it contains the domain of the immediately preceding parent address.

$parent_local_part: This variable is empty, except when a `child' address (generated by aliasing or forwarding, for example) is being processed, in which case it contains the local part of the immediately preceding parent address.

$primary_hostname: The value set in the configuration file, or read by the uname() function.

$qualify_domain: The value set for this option in the configuration file.

$qualify_recipient: The value set for this option in the configuration file, or if not set, the value of $qualify_domain.

$received_protocol: When a message is being processed, this variable contains the name of the protocol by which it was received.

$reply_address: When a message is being processed, this variable contains the contents of the Reply-To: header line if one exists, or otherwise the contents of the From: header line. However, if the message contains a set of ``Resent-'` header lines, their contents are used in preference.

$return_path: When a message is being delivered, this variable contains the return path -- the sender field that will be sent as part of the envelope. It is not enclosed in <> characters. In many cases, $return_path has the same value as $sender_address, but if, for example, an incoming message to a mailing list has been expanded by a director which specifies a specific address for delivery error messages, $return_path contains the new error address, while $sender_address contains the original sender address that was received with the message.

$sender_address: When a message is being processed, this variable contains the sender's address that was received in the message's envelope. For delivery failure reports, the value of this variable is the empty string.

$sender_address_domain: The domain portion of $sender_address.

$sender_address_local_part: The local part portion of $sender_address.

$sender_fullhost: When a message is received from a remote host, this variable contains the host name and IP address in a single string, which always ends with the IP address in square brackets. If log_incoming_port is set, the port number on the remote host is added to the IP address, separated by a full stop. The format of the rest of the string depends on whether the host issued a HELO or EHLO SMTP command, and whether the host name was verified by looking up its IP address. A plain host name at the start of the string is a verified host name; if this is not present, verification either failed or was not requested. A host name in parentheses is the argument of a HELO or EHLO command. This is omitted if it is identical to the verified host name or to the host's IP address in square brackets.

$sender_helo_name: When a message is received from a remote host that has issued a HELO or EHLO command, the first item in the argument of that command is placed in this variable. It is also set if HELO or EHLO is used when a message is received using SMTP locally via the -bs or -bS options.

$sender_host_address: When a message is received from a remote host, this variable contains that host's IP address.

$sender_host_name: When a message is received from a remote host, this variable contains the host's name as verified by looking up its IP address. If verification failed, or was not requested, this variable contains the empty string.

$sender_host_port: When a message is received from a remote host, this variable contains the port number that was used on the remote host.

$sender_ident: When a message is received from a remote host, this variable contains the identification received in response to an RFC 1413 request. When a message has been received locally, this variable contains the login name of the user that called Exim.

$sn0 -- $sn9: These variables are copies of the values of the $n0 -- $n9 accumulators that were current at the end of the system filter file. This allows a system filter file to set values that can be tested in users' filter files. For example, a system filter could set a value indicating how likely it is that a message is junk mail.

$thisaddress: This variable is set only during the processing of the foranyaddress command in a filter file. Its use is explained in the description of that command.

$tod_bsdinbox: The time of day and date, in the format required for BSD-style mailbox files, for example: Thu Oct 17 17:14:09 1995.

$tod_full: A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40 +0100. The timezone is always given as a numerical offset from GMT.

$tod_log: The time and date in the format used for writing Exim's log files, for example: 1995-10-12 15:32:29.

$value: This variable contains the result of an expansion lookup operation, as described above. If $value is used in other circumstances, its contents are null.

$version_number: The version number of Exim.

Go to the first, previous, next, last section, table of contents.