5.6 Action List

An action list is a list of action commands, which control processing of an outgoing messages. All action command names are case insensitive, so you can use for instance: ‘add’ or ‘ADD’ or ‘AdD’, and so on.

5.6.1 Stop Action

The stop command stops immediately the processing of the section. It may be used in the main RULE section as well as in any user-defined section. For example:

if not header[Content-Type] "text/plain; .*"
  stop;
fi

5.6.2 Call Action

The call command allows to invoke a user-defined section much in the same manner as a subroutine in a programming language. The invoked section continues to execute until its end or the stop statement is encountered, whichever the first.

BEGIN myproc
if header[Subject] "Re: .*"
  stop;
fi
trigger "pgp"
  gpg-encrypt "my_gpg_key"
done
END

BEGIN RULE
call myproc
END

5.6.3 Adding Headers or Text

The add command allows you to add arbitrary headers or text to the message. To add a header, use the following syntax:

Command: add header ‘[’name‘]’ string

Command: add ‘[’name‘]’ string

For example:

add header[X-Comment-1] "GNU's Not Unix!" add [X-Comment-2] "Support FSF!"

Command: add body text

Adds the text to the message body. Use of this command with ‘here document’ syntax allows to append multi-line text to the message, e.g.:

add body <<-EOT Regards, Hostmaster EOT

5.6.4 Removing Headers

The command remove removes the specified header from the message. The syntax is:

Command: remove [flags] header ‘[’string‘]’

Command: remove [flags] ‘[’string‘]’

The name of the header to delete is given by string parameter. By default only those headers are removed whose names match it exactly. Optional flags allow to change this behavior. See section Regular Expressions, for the detailed description of these.

An example:

remove ["X-Mailer"] remove :regex ["^X-.*"]

The first example will remove the ‘X-Mailer:’ header from an outgoing message, and the second one will remove all "X-*" headers.

5.6.5 Modifying Messages

The action command modify allows to alter the headers or the body of the message.

Command: modify [flags] header ‘[’key‘]’ ‘[’new-key‘]’

Command: modify [flags] ‘[’key‘]’ ‘[’new-key‘]’

For each header whose name matches key, replaces its name with new-key. If key is a regular expressions, new-key may contain back references. For example, the following statement will select all headers whose names start with ‘X-’ and change their names to begin with ‘X-Old-’:

modify header :re ["X-\(.*\)"] ["X-Old-\1"]

Command: modify [flags] header ‘[’key‘]’ value

Command: modify [flags] ‘[’key‘]’ value

For each header whose name matches key, changes its value to value. For example:

modify [Subject] "New subject"

This statement sets the new value to the Subject header.

Every occurrence of unescaped ‘&’ in the new value will be replaced by the old header value. To enter the ‘&’ character itself, escape it with two backslash characters (‘\\’). For example, the following statement

modify [Subject] "[Anubis \\& others] &"

prepends the Subject header with the string ‘[Anubis & others]’. Thus, the header line

Subject: Test subject

after having been processed by Anubis, will contain:

Subject: [Anubis & others] Test subject

Command: modify [flags] header ‘[’key‘]’ ‘[’new-key‘]’ value

Command: modify [flags] ‘[’key‘]’ ‘[’new-key‘]’ value

Combines the previous two cases, i.e. changes both the header name and its value, as shown in the following example:

modify header [X-Mailer] [X-X-Mailer] "GNU Anubis"

Command: modify [flags] body ‘[’key‘]’

Removes all occurrences of key from the message body. For example, this statement will remove every occurrence of the word ‘old’:

modify body ["old"]

Command: modify [flags] body ‘[’key‘]’ string

Replaces all occurrences of key with string. For example:

modify body :extended ["the old \([[:alnum:]]+\)"] "the new \1"

5.6.6 Inserting Files

Command: signature-file-append yes-or-no

This action command adds at the end of a message body the ‘-- ’ line, and includes a client's ‘~/.signature’ file. Value ‘no’ is the default.

Command: body-append file-name

This action command includes at the end of a message body the contents of the given file. If ‘file-name’ does not start with a ‘/’ character, it is taken relative to the current user home directory

Command: body-clear

Removes the body of the message

Command: body-clear-append file-name

Replaces the message body with the contents of the specified file. The action is equivalent to the following command sequence:

body-clear body-append file-name

5.6.7 Mail Encryption

Command: gpg-passphrase passphrase

Specifies your private key's pass phrase for signing an outgoing message using the GNU Privacy Guard (a tool compatible with the Pretty Good Privacy). Of course, to protect your passwords in the configuration file use the 0600 (u=rw,g=,o=) permissions, otherwise GNU Anubis won't accept them. We recommend setting the ‘gpg-passphrase’ once in your configuration file, e.g. at the start of RULE section.

GNU Anubis supports the GNU Privacy Guard via the GnuPG Made Easy library, available at http://www.gnupg.org/gpgme.html.

Command: gpg-encrypt gpg-keys

This command enables encrypting your outgoing message with the GNU Privacy Guard (Pretty Good Privacy) public key(s). gpg-keys is a comma separated list of keys (with no space between commas and keys).

gpg-encrypt "John's public key"

Command: gpg-sign gpg-signer-key

Command: gpg-sign ‘yes-or-default’

This command signs the outgoing message with your GNU Privacy Guard private key. Specify a passphrase with gpg-passphrase. Value ‘default’ means your default private key, but you can change it if you have more than one private key.

For example:

gpg-sign default

or

gpg-passphrase "my office key passphrase" gpg-sign office@example.key

Command: gpg-sign-encrypt gpg-keys[:gpg-signer-key]

Command: gpg-se gpg-keys[:gpg-signer-key]

This command simultaneously signs and encrypts your outgoing message. It has the same effect as gpg command line switch ‘-se’. The argument before the colon is a comma-separated list of PGP keys to encrypt the message with. This argument is mandatory. The second argument is optional and is separated from the first one by a colon (‘:’). This argument specifies the signer key. In the absence of the second argument your default private key is used.

For example:

gpg-sign-encrypt John@example.key

or

gpg-se John@example.key:office@example.key

5.6.8 Using an External Processor

Command: external-body-processor program [args]

Pipes the message body through program. program should be a filter program, that reads the text from the standard input and prints the transformed text on the standard output. The output from the program replaces the body of the message. args are any additional arguments the program may require.

The amount of data fed to the external program depends on the message. For plain messages, the entire body is passed. For multi-part messages, only the first part is passed by default. This is based on the assumption that in most multi-part messages the first part contains textual data, while the rest contains various (mostly non-textual) attachments. There is a special configuration variable read-entire-body that controls this behavior (see section Basic Settings). Setting read-entire-body yes in CONTROL section of your configuration file instructs Anubis to pass the entire contents of multi-part messages to your external processor.

There is a substantial difference between operating in read-entire-body no (the default) and read-entire-body yes modes. When operating in read-entire-body no, the first part of the message is decoded and then passed to the external program. In contrast, when read-entire-body is set to yes, the message is not decoded. Thus, your external processor must be able to cope with MIME messages.

5.6.9 Quick Example

Here is a quick example of using an action list:

---BEGIN RULE---
if header [X-Mailer] :re ".*"
   remove [X-Mailer]
   add [X-Comment] "GNU's Not Unix!"
   gpg-sign "my password"
   signature-file-append yes
fi
---END---

The example above will remove (on-the-fly) the ‘X-Mailer:’ line from an outgoing message, add an extra header line (‘X-Comment:’), sign your message with your private key, and add a simple signature file from your home directory.

This document was generated by Sergey Poznyakoff on December, 20 2008 using texi2html 1.78.