PEP Documentation

Pages: Quickstart • Actions • Headers • Tests • Commands • Attachment Handling • Reply Files • Mailing Lists • Child Accounts • DNS Blocklists • SpamAssassin • Challenges • M-Script • Glossary • Spam FAQ • SMTP Tutorial • PEP Quick Setup • PEP Wizard • PEP Editor

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}

ARCHIVE

This action saves the message into a ZIP archive in your account. All headers and body content are included. It takes a single parameter which is the name of a ZIP archive. If the ZIP archive does not exist it is created automatically. If it does exist then the message is appended to it.

This example creates a monthly email backup (one month of messages per ZIP file):

archive if true to "mailbackup-%Y-%m.zip"

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@islandnet.com"

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 10,000 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.

For a full-blown mailing list system built around the DISTRIBUTE action, please see the mailing list page.

ENCRYPT

This action will encrypt the body of the message using a specified public key from your GNUpg keyring (you must have first added a public key using the keyring manager).

To encrypt certain messages using the public key for "John Doe":

encrypt if subject contains "online order" with "John Doe <jdoe@example.com>"

EXEC

This action runs an M-Script program. It takes two parameters: the first is required and is the name of the program to run, the second is optional and is the name of a file to save the message to.

If no filename is specified, the program runs but it can't access the message. If a filename is given, the message is saved to the file and then the program is launched. The program can then read the file if necessary.

If the program exits with a return code of zero, PEP halts and the message is effectively deleted. If the program exits with a return code of one, PEP continues to test the message against the remaining rules in the file.

Click here for more detailed information about the EXEC action.

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.

FAX

This action forwards the current message to a fax machine. You can only forward a message to a single fax number, but it can be anywhere in North America. The fax number must be exactly 10 digits long for local (to Victoria, BC, Canada) numbers, or 11 digits long (for anywhere else in North America). Include no dashes, spaces, letters, or anything else in the number. Messages longer than 250 lines long will not be faxed.

This example forwards web orders our local fax number:

fax if subject contains "web order" to "2503830096"

This one forwards web orders a non-local number:

fax if subject contains "web order" to "16045551234"

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@islandnet.com"

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 "islandnet.com"

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.

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.

PAGE

This action sends a message to a pager or cell phone device. Supported pager/cell phone systems include Radioworks, Telus, TelusMike, Cantel, CantelPCS, Clearnet, ClearnetMike, Microcell, and Sprint.

This action requires noe parameter that specifies the service and PIN number for your pager or cell phone, separated by a dash. For example, if your pager service is Radioworks and your pager number is 5551234, you'd specify "RADIOWORKS-5551234" as a parameter.

A second parameter, which is optional, is the message to be sent. This defaults to "PEP: {from} - {subject}" unless you specify something else (where {from} and {subject} are replaced with values from the message in question.

This example notifies me via pager whenever a new order arrives:

page if subject contains "web order" "RADIOWORKS-5551234" "New order from {from}"

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 "islandnet.com" -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

STRIP

This action strips out (removes) a specific header before the message is saved or forwarded. This action does not cause PEP to exit, the current message continues to be tested against subsequent rules. The header name may contain wildcards too, if you want to strip out a whole set of similar headers.

To remove the X-Spam-Report: header, use a rule like this:

strip if true X-Spam-Report

To remove ALL of the X-GeoIP-* headers, use a rule like this:

strip if true X-GeoIP-*