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


Generic options for transports

The generic options for transports are as follows:

body_only (transport) option

Option: body_only
Type: boolean
Default: false

If this option is set, the message's headers are not transported. It is mutually exclusive with `headers_only'. If it is used with the `appendfile' or `pipe' transports, the settings of `prefix' and `suffix' should be checked, since this option does not automatically suppress them.

debug_print (transport) option

Option: debug_print
Type: string
Default: unset

If this option is set and debugging is enabled (see `-d', `-v', and `debug_level'), then the string is expanded and included in the debugging output when the transport is run. This is to help with checking out the values of variables and so on when debugging driver configurations. For example, if a `headers_add' option is not working properly, `debug_print' could be used to output the variables it references. A newline is added to the text if it does not end with one.

delivery_date_add (transport) option

Option: delivery_date_add
Type: boolean
Default: false

If this option is true, a `Delivery-date:' header is added to the message. This gives the actual time the delivery was made. As this is not a standard header, Exim has a configuration option (`delivery_date_remove') which requests its removal from incoming messages, so that delivered messages can safely be resent to other recipients.

driver (transport) option

Option: driver
Type: string
Default: unset

This specifies which of the available transport drivers is to be used. For example:


driver = smtp

There is no default, and this option must be set for every transport.

envelope_to_add (transport) option

Option: envelope_to_add
Type: boolean
Default: false

If this option is true, an `Envelope-to:' header is added to the message. This gives the original address(es) in the incoming envelope that caused this delivery to happen. More than one address may be present if `batch' or `bsmtp' is set on transports that support them, or if more than one original address was aliased or forwarded to the same final address. As this is not a standard header, Exim has a configuration option (`envelope_to_remove') which requests its removal from incoming messages, so that delivered messages can safely be resent to other recipients.

headers_add (transport) option

Option: headers_add
Type: string
Default: unset

This option specifies a string of text which is expanded and added to the header portion of a message as it is transported. If the result of the expansion is an empty string, or if the expansion is forced to fail, no action is taken. Other expansion failures are treated as errors and cause the delivery to be deferred. The expanded string should be in the form of one or more RFC 822 header lines, separated by newlines (coded as `\n' inside a quoted string), for example:


headers_add = "X-added: this is a header added at $tod_log\n\
               X-added: this is another"

Exim does not check the syntax of these added headers. A newline is supplied at the end if one is not present. The text is added at the end of any existing headers. If you include a blank line within the string, you can subvert this facility into adding text at the start of the message's body.

The name `add_headers' was formerly used for this option, and is retained as a synonym for backward compatibility. Additional headers can also be specified by directors and routers. See chapter "Common generic options for directors and routers" and section "Adding and removing headers" in chapter "Message processing".

headers_only (transport) option

Option: headers_only
Type: boolean
Default: false

If this option is set, the message's body is not transported. It is mutually exclusive with `body_only'. If it is used with the `appendfile' or `pipe' transports, the settings of `prefix' and `suffix' should be checked, since this option does not automatically suppress them.

headers_remove (transport) option

Option: headers_remove
Type: string
Default: unset

This option consists of a colon-separated list of header names, not including the terminating colon, for example:


headers_remove = "return-recipt-to:acknowledge-to"

Any existing headers matching those names are not included in any message that transmitted by the transport. However, added headers may have these names. Thus it is possible to replace a header by specifying it in `remove_headers' and supplying the replacement in `add_headers'.

The name `remove_headers' was formerly used for this option, and is retained as a synonym for backward compatibility. Headers to be removed can also be specified by directors and routers. See chapter "Common generic options for directors and routers" and section "Adding and removing headers" in chapter "Message processing".

message_size_limit (transport) option

Option: message_size_limit
Type: integer
Default: 0

This option controls the size of messages passed through the transport. If its value is greater than zero and the size of a message message exceeds the limit, the address is failed. If there is any chance that the resulting bounce message could be routed to the same transport, you should ensure that `return_size_limit' is less than the transport's `message_size_limit', as otherwise the bounce message will fail to get delivered.

return_path (transport) option

Option: return_path
Type: string
Default: unset

If this option is set, the string is expanded at transport time and replaces the existing return path (envelope sender) value. The expansion can refer to the existing value via `$return_path'. If the expansion is forced to fail, no replacement occurs; if it fails for another reason, Exim panics. This option can be used to support VERP (Variable Envelope Return Paths) -- see chapter "SMTP processing".

return_path_add (transport) option

Option: return_path_add
Type: boolean
Default: false

If this option is true, a `Return-path:' header is added to the message. Although the return path is normally available in the prefix line of BSD mailboxes, this is commonly not displayed by MUAs, and so the user does not have easy access to it.

RFC 822 states that the `Return-path:' header is `added by the final transport system that delivers the message to its recipient' (section 4.3.1), which implies that this header should not be present in incoming messages. Exim has a configuration option, `return_path_remove', which requests removal of this header from incoming messages, so that delivered messages can safely be resent to other recipients.

shadow_condition (transport) option

Option: shadow_condition
Type: string
Default: unset

See `shadow_transport' below.

shadow_transport (transport) option

Option: shadow_transport
Type: string
Default: unset

This facility is somewhat experimental, and may change in future. A local transport may set the `shadow_transport' option to the name of another, previously-defined, local transport. Shadow remote transports are not supported.

Whenever a delivery to the main transport succeeds, and either `shadow_condition' is unset, or its expansion does not result in a forced expansion failure or the empty string or one of the strings `0' or `no' or `false', the message is also passed to the shadow transport. However, the result of the shadow transport is discarded and does not affect the subsequent processing of the message. Only a single level of shadowing is provided; the `shadow_transport' option is ignored on any transport when it is running as a shadow. Options concerned with output from pipes are also ignored.

The log line for the successful delivery has an item added on the end, of the form


ST=<shadow transport name>

If the shadow transport did not succeed, the error message is put in parentheses afterwards.

Shadow transports can be used for a number of different purposes, including keeping more detailed log information than Exim normally provides, and implementing automatic acknowledgement policies based on message headers that some sites insist on.

transport_filter (transport) option

Option: transport_filter
Type: string
Default: unset

This option sets up a filtering (in the Unix shell sense) process for messages at transport time. It should not be confused with mail filtering as set up by individual users.

When the message is about to be written out, the command specified by `transport_filter' is started up in a separate process, and the entire message, including the headers, is passed to it on its standard input (this in fact is done from a third process, to avoid deadlock). This happens before any SMTP-specific processing, such as turning `\n' into `\r\n' and escaping lines beginning with a dot.

The filter's standard output is read and written to the message's destination. The filter can perform any transformations it likes, but of course should take care not to break RFC 822 syntax. A demonstration Perl script is provided in `util/transport-filter.pl'; this makes a few arbitrary modifications just to show the possibilities.

A problem might arise if the filter increases the size of a message that is being sent down an SMTP channel. If the receiving SMTP server has indicated support for the SIZE parameter, Exim will have sent the size of the message at the start of the SMTP session. If what is actually sent is substantially more, the server might reject the message. This can be worked round by setting the `size_addition' option on the `smtp' transport, either to allow for additions to the message, or to disable the use of SIZE altogether.

The value of the option is the command string for starting up the filter, which is run directly from Exim, not under a shell. The string is parsed by Exim in the same way as a command string for the `pipe' transport: Exim breaks it up into arguments and then expands each argument separately. The special argument `$pipe_addresses' is replaced by a number of arguments, one for each address that applies to this delivery. (This isn't an ideal name for this feature here, but as it was already implemented for the `pipe' transport, it seemed sensible not to change it.)

The expansion variables `$host' and `$host_address' are available when the transport is a remote one. They are set only for the expansion of a transport filter command, as that is the only thing that is expanded after a connection has been set up. For example:


transport_filter = "/some/directory/transport-filter.pl \
  $host $host_address $sender_address $pipe_addresses"

The filter process is run under the same uid and gid as the normal delivery. For remote deliveries this is the exim uid/gid if they are defined.

If a transport filter is set on an autoreply transport, the original message is passed through the filter as it is being copied into the newly generated message, which happens if the `return_message' option is set.


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