Message Filters

Email filtering rules, called Message Filters, are run by the mail server and automatically perform actions on incoming emails. (They are procmail filters.) The filters can be created for any full-hosted mail account and are stored on the mail server and applied to all incoming mail, after any Anti-spam filtering is applied. Many mail programs have their own message rules or filters, including Outlook and Thunderbird. Mail program filters would be applied after the server's filters.

Message filters are a great way to make incoming emails easier to sort through. You can automatically label important emails, and sort some emails into subfolders to read later.

Examples

 * Label all emails from your boss important
 * add IMPORTANT to the subject of emails with boss@example.com in the from


 * Move emails from the zoo's mailing list to the Zoo List folder to read later
 * move emails to Zoo List that match all of the following:
 * contain discussion@zoo.example.com in the from to Zoo List
 * contain [ZL] in the Subject


 * Delete emails from an ex-friend
 * delete emails that match any of the following:
 * contains joe@example.com in the from
 * contains Joe Smith in the from

Where?
Message Filters can be viewed, created, and edited from a few different places. Each place has the same options, there is no difference between them. You can use whatever one you prefer, and switch between them at any time.
 * Panel's Mail -> Message Filters page (requires panel access)
 * Page lists all the fully hosted mail accounts and the number of filters on each; click the Edit button to view an individual mail account's filters.  Click the 'Add New Filter' button to make a new filter, or work with the existing filters by using the "Move Up/Down" buttons to reorder them or the Delete or Edit buttons to adjust an individual filter.


 * Mailboxes website for your domain, http://mailboxes.YOURDOMAIN.COM/ or https://mailboxes.YOURDOMAIN.COM, or main mailboxes DreamHost website, http://mailboxes.dreamhost.com or https://mailboxes.dreamhost.com (requires the mail account password only)
 * Scroll down to Email Filters to view all the filters on the mail account. Click the 'Add New Filter' button to make a new filter, or work with the existing filters by using the "Up/Down" links to reorder them or the Delete or Edit links to adjust an individual filter.


 * Mail API (requires an API key generated in the panel's Web Panel API page)
 * Use mail-list_filters to list all filters on all mail accounts, and use mail-add_filter or mail-remove_filter to add or remove filters.

How?
Some general notes to keep in mind when setting up filters:
 * Order matters! The rules are checked one by one, so be sure you have them listed in the order you want them to be checked or executed.
 * Most rules should be made with "If this filter matches" "execute and stop". Only use "execute and continue" if you want to do multiple actions to a single incoming email.

When picking what part of the email to have the rule check ("When an email's ____ contains"), here's some information where each option looks:
 * Subject -- Looks in the Subject line of the email. It looks everywhere in the subject line, and can match part or all of the Subject.
 * Example: match "drink" in "Subject: Eat, drink, and be merry!"
 * From -- Looks in the From line of the email, checking for who sent the email. It looks everywhere in the From line, and can match part or all of the From line.
 * Example: match "bob" in "From: bob@work.com"
 * Example: match "Jones" in "From: Bob Jones "
 * To -- Looks in the To line of the email, checking for who the email was sent to. It starts searching directly after "To"; use .* to match any part of the the name or email address anywhere in the line.
 * Example: match "George" in "To: George of the Jungle "
 * Tip: Combine this rule with using '+' for slightly customized email addresses for easy sorting of emails from websites. Give Amazon your email address as you+amazon@yourdomain.com and then you can easily filter those emails.
 * Example: match ".*books" in "To: me+books@mywebsite.com"
 * CC -- Looks in the CC line(s) of the email, checking for other people the email was sent to.
 * Headers -- Looks at the beginning of every line in the email; intended for use matching header lines, such as "X-Spam: Yes".  Note that this checks the entire email, the message body and the headers.
 * Example: match "X-Spam: Yes" in the email's headers
 * Tip: use .* to match anywhere in the line, not just the beginning. (This makes the procmail pattern ^.*STRING versus ^STRING.)
 * Example: match ".*bananas" to match "bananas" anywhere in any line of the email
 * Reply-To -- Looks in the Reply-To line of the email, the email address where replies to the email are sent.
 * Body -- Looks in the message body of the email, and does not look in the headers.

When choosing an action ("Do this"), here's some additional information on each option:
 * Move it to folder -- Puts the email in the specified folder. This is possibly the most useful action, but there are a few caveats/restrictions.
 * The folder must already exist, the filter cannot make the folder for you. If you enter a folder name that does not exist the emails will be deleted instead of moved.
 * Folder names are cAsE sEnSiTiVe! Double-check your folder name's spelling and shift key usage.
 * The filters can not use folder names that have spaces in the name. Subfolders are okay, but must be specified with the parent folder and a '.', like ParentFolder.SubFolder.  Folder names can only contain only letters, numbers, underscores, dots, and dashes. (But no leading dots, trailing dots, or double dots!)
 * Add this to the subject -- Adds the specified text to the beginning of the email's subject line.
 * Example: "Subject: Test Email" becomes "Subject: ADDED_TEXT Test Email"
 * Add this header -- Adds the specified text to the header area of the email. This added text will not be visible when the email is displayed normally, it will only be visible when viewing all the headers.
 * Forward it to email address -- What it says. The email address to forward the email to can be any address, hosted at DreamHost or anywhere else.
 * Forward to shell account -- Forward the email to the Maildir of a shell user. This is the same as forwarding to an email address and specifying shell_user@server_name.dreamhost.com.
 * Delete it -- What it says. The email is not put in the Trash folder, it is completely erased.

Doing more than one action
Each individual message filter can check for multiple things but can only perform a single action. You can use "execute and continue" to have multiple actions done on a single email. When a filter has "execute and continue" the action from the matching filter is taken, and then the next filter is checked and filtering continues. Normally filters are made with "execute and stop" and the first rule that matches is the only action taken, no more filters are checked.

Here's a example set of filters that check for spam and also sort mail into folders:
 * add POSSIBLE SPAM to the subject of emails any of the following
 * contains viagra in the Subject
 * contains diet in the Subject
 * contains monkey in the Subject
 * and then continue


 * move emails to Amazon with Amazon in the Subject
 * and then stop


 * move emails to Twitter with twitter.com in the From
 * and then stop

Using message filters with the Junk Mail filters
You can still use the message filters even if the domain is set up with the Anti-spam junk mail filtering. Mail will come in through the junk mail filtering machines first, then gets routed to the regular incoming mail machines. Emails that are quarantined go there before your keyword filters are applied.

What do the procmail rules actually look like?
Here's some examples of message filters, and the procmail rule created to execute it.

move emails with bananas in the subject to MONKEY and then stop. :0 * ^subject:.*bananas .MONKEY/

move emails with bananas in the from to MONKEY and then stop. :0 Wf * ^from:.*bananas .MONKEY/

add the header X-header: MONKEY to emails with bananas in the to and then stop. :0 Wf * ^TObananas | formail -A "X-header: MONKEY"

forward emails with bananas in the cc to MONKEY@TheZoo.US and then stop. :0 * ^cc:.*bananas ! MONKEY@TheZoo.US

forward emails with bananas in the headers to FTP_USER on WEB_SERVER and then stop. :0 * ^bananas ! FTP_USER@WEB_SERVER.dreamhost.com

move emails with bananas in the reply-to to MONKEY and then stop. :0 Wf * ^reply-to:.*bananas .MONKEY/

move emails with bananas in the body to MONKEY and then stop. :0 Wf * B ?? bananas .MONKEY/