Help Documents: PEP

Actions

     ACTION if HEADERS TEST VALUE [P1] [P2]

A rule tests one or more headers against a value, and if the result is true, the action is performed. If the result is false, the rule is skipped.

NOTE:

• Some actions require one or even two parameters, some don't use any, and some take optional parameters.
• Some actions (eg: DELETE) cause PEP to exit immediately, while others (eg: SCORE) perform an action and carry on.

Here is a list of all the actions that PEP recognises:

APPEND

This action appends a line of text to a file in your account. It takes two parameters: the first is the file you want to write to, and the second is the text you want to write to it. This is a handy action if you want to create custom log files.

NOTE:

• If the file doesn't exist, it is created.
• Any existing file contents are not overwritten.
• A newline character is always added to the file after the text is appended.

This example adds the value of the From: header to the file "spammers" if the message has a high Spam Assassin score:

append if sascore > 5 spammers {from}

BSAVE

This action saves the body of the message to a file in your account. The headers are not included. It takes a single parameter which is the name of the file to save to. You could use this action to allow updating of a web page via e-mail, for example.

NOTE:

• If the file doesn't exist, it is created.
• If the files exists, it is overwritten.
• The body is saved as-is, no MIME decoding is performed.

This example replaces the file "schedule.txt" in your "www" directory:

bsave if subject contains "newschedule" "www/schedule.txt"

CHALLENGE

This action helps to eliminate spam by ensuring that you only get mail from real e-mail addresses. If you get mail from an unrecognised sender, the message is "frozen" until the sender responds to a challenge message confirming his address. If the sender replies to the challenge, the message is "thawed" and processed again by PEP. If the sender does not reply, the message is deleted. It requires a single parameter which is the name of the reply file to send as a challenge.

This example issues a challenge for messages that score high on the spam meter:

challenge if sascore > 7 "challenge.txt"

Click here for more detailed information about challenges.

CLASSIFY

This action is under construction. It is part of a new anti-spam feature and allows you to train a Bayesian filter. Watch page for updates.

COPY

This action combines the KEEP and FORWARD actions into a single action. The message is delivered to your mailbox and a copy is also sent to an e-mail address you specify. It takes a single parameter, which is the e-mail address to send the copy to.

NOTE: You can only copy a message up to three times in your mailrule file. It's not intended to be used to implement a mailing list.

This example sends copies of our web orders to our sales department:

copy if subject contains "web order" "sales@christian.net"

DELETE

This action deletes the current message and stops processing your mailrule file.

Example:

delete if origin contains "hotmail.com"

DISTRIBUTE

This action forwards a message on to a list of up to 500 addresses. You must supply it with one parameter that is the name of a file in your account that contains the list of addresses (one address per line, blank lines and lines that begin with a '#' mark are ignored).

By default, the message that the recipients receive will appear to come directly from the original sender, which means any replies they make will go back to that person. By supplying a second optional parameter you can change the sender's address to anything you want. This would normally be used to set it to the address for your list, so that any replies will be re-distributed to everyone (that's the difference between a mailing list and a discussion list).

Examples:

distribute if envelope-to is "list@mydomain.com" "list.txt" distribute if envelope-to is "list@mydomain.com" "list.txt" "list@mydomain.com"

NOTE: Never add people to your mailing lists unless they explicitly asked to be added, and never assume that a signup request submitted via a web form really came from the person it says it did. Always confirm signup requests via email (or some other reliable means) before adding someone to your list.

FAIL

This action deletes the current message like DELETE, but it also generates an error message that gets sent back to the sender.

Unlike a reply file, the message that is sent back is an actual delivery error message, just like you'd get if there was a real error.

The default error message is "No such user.", which makes it look like the original message was sent to an invalid address. You can optionally specify a single parameter that contains a different message.

This example bounces back to the sender with a "No such user." error:

fail if origin contains "hotmail.com"

This example bounces back with a "Spam not welcome here." error:

fail if origin contains "yahoo.com" "Spam not welcome here."

NOTE: Please use this action sparingly. Most spam doesn't have a valid return address anyway, so using this action just fills up our mail server's queue with error messages that can never be delivered.

FORWARD

This action forwards the current message to another address and does not deliver it to your mailbox. It takes a single parameter which is the address to forward the message to.

NOTE: You can only forward a message up to three times in your mailrule file. It's not intended to be used to implement a mailing list.

This example forwards web orders to our sales department:

forward if subject contains "web order" "sales@christian.net"

This example forwards all messages to another address:

forward if * matches * "bob@hotmail.com"

INSERT

This action inserts a new header into the current message. If the message gets delivered to your mailbox, the headers you've added will be present. It takes two parameters: the first is the name of the header you want to add, and the second is the value for that header.

This example adds an X-SPAM: header that contains the current PEP score value:

insert if * matches * X-SPAM {score}

NOTE: User-added headers are only added to messages that are delivered to your mailbox. They do not get added to messages that you forward elsewhere.

JUMP

This action jumps ahead in the mailrule file, skipping over lines. With this action you can create sets of rules that only get tested if some other condition is true. It takes a single parameter which is a label to jump to. If the test is true, PEP skips ahead in the file looking for a line that begins with an '@' sign followed by the label. If the matching label line isn't found, PEP delivers the message and exits.

This example deletes messages that contain an X-UIDL header, but only if there are no Resent-* headers:

jump if resent-* matches * SKIP delete if x-uidl matches * @SKIP

KEEP

This action keeps the current message and exits. In other words, the current mesage is delivered into your mailbox. This is the default action if a message makes it through all your rules without being deleted.

Example:

keep if from contains "christian.net"

MSAVE

This action extracts a MIME file attachment from the current message and saves it to a file. It takes a single parameter which is the name of the file to save it to.

NOTE:

• If the file doesn't exist, it is created.
• If the files exists, it is overwritten.
• If there are multiple attachments in the message, only the first one is extracted.

This example replaces the file "logo.jpg" in your "www" directory:

msave if subject contains "logoupdate" "www/logo.jpg"

NOTIFY

This action is the same as DELETE except that a brief notice is put into your mailbox. The notice tells you which rule matched the message and it includes the headers.

REPLY

This action is the same as DELETE except that a reply file is mailed back to the sender. It takes two parameters: the name of the reply file to send back, and the address to send it to (this second parameter is optional and rarely needed - replies will normally go back to the sender of the original message).

This example sends the file "menu.txt" back in response to certain messages:

reply if subject contains "menu" "menu.txt"

This example sends the file "schedule.txt" back in response to certain messages. Replies are sent to the address found in the Return-path: header by default, but in this case we want to send it to the address in the Reply-to: header instead:

reply if subject contains "schedule" "schedule.txt" "{replyaddress}"

SAVE

This action saves the message to a file in your account. The entire message is saved, headers and all. It takes a single parameter, which is the name of the file to save the message to.

NOTE:

• If the file doesn't exist, it is created.
• If the files exists, it is NOT overwritten, the message is appended.
• The file created is a valid UNIX style mailbox, which is compatible with PINE and ELM and other mail programs.

This example saves certain messages to a folder that can be accessed with PINE or ELM:

save if subject contains "[llamas]" "Mail/llamalist"

SCORE

PEP has an internal "score" value that starts out at zero. This action lets you add to the score, subtract from the score, or set the score to a particular value. The score can be positive or negative, but it's always a whole number. This action does not cause PEP to exit, the current message continues to be tested against subsequent rules.

To add to the score, use a rule like this:

score if origin contains "hotmail.com" +10

To subtract from the score, use a rule like this (note the minus sign):

score if origin contains "christian.net" -10

To set the score to a specific value, use a rule like this (note the equal sign):

score if x-rbl-warning matches * =1000

To test the current score value, use a rule like this:

delete if score > 30