IMPORTANT NOTES

{MAILSERVER} = Your current Mail Server i.e. IMail or SmarterMail

If you are a SmarterMail user you can rely on using SmarterMail anti-spam settings as declude passes the weight of the messages to SmarterMail. If you want to understand better how declude operates then the rest of the manual applies.

1. Installation & Upgrades

1.1 Overview

After Declude JunkMail is installed, it will intercept every E-mail going through the {MAILSERVER}.

Declude JunkMail runs a number of tests on each E-mail. It will then perform an action on each E-mail that is considered spam. The actions can vary depending on the test, as some tests are less lenient than others.

For example, you could set up Declude JunkMail so that mail failing the MAILFROM test to would be deleted, while mail failing the DSBLALL test would have a warning appended to the headers of the message.

2. Files

2.1 \{MAILSERVER}\Declude.exe - The main Declude executable file. This is automatically started by the {MAILSERVER} as needed. Note that it must be in the \{MAILSERVER}\ directory, not the \{MAILSERVER}\Declude\ directory.

2.2 \{MAILSERVER}\Declude\global.cfg - This contains the "global" Declude JunkMail settings. It includes standard settings (such as whether to add the spool file name to the E-mail headers with the XSPOOLNAME option), test definitions (which you shouldn't normally need to change or worry about), and the actions to take for outgoing E-mails . This is not a script (Declude doesn't use scripts), it is a standard configuration file, so there is no order to it (if adding lines to it, you can put them anywhere in the file).

2.3 \{MAILSERVER}\Declude\$default$.JunkMail - This file is the one you will use most. It simply determines the actions to take when incoming E-mail (spam) fails the various tests. Each line determines the action to take for a specific test; for example, "ORBZ WARN" lets Declude JunkMail know to add a standard "X-RBL-Warning:" header for E-mail that fails the ORBZ test.

2.4 Other Files - Any other files in the \{MAILSERVER}\Declude\ directory (or its subdirectories) are "per-user" or "per-domain" configuration files (see the "Per-User" and "Per-Domain" sections of the manual for more information). These files are in the exact same format as the \{MAILSERVER}\Declude\$default$.JunkMail file.

3. Basic Configuration

By default, Declude JunkMail will add one warning to the headers of the E-mail for each spam test that the E-mail fails. You may want to run it like this for a few days, and look at the E-mails you receive (and/or the Declude JunkMail log file) to see what it considers spam.

Note that many of the tests (such as REVDNS and SPAMHEADERS) will catch a large amount of spam, but will also have many false positives. If spam tests were 100% perfect, there would only be one spam test. Therefore, most people will not block E-mail on many of the tests. If you want to quickly start blocking spam, you should consider blocking the mail that fails the WEIGHT10 test (or WEIGHT20 test, to allow more spam through in order to further reduce false positives). The weighting tests will significantly reduce false positives, by only catching mail that fails several tests.

To change the actions that Declude JunkMail takes on spam (for example, to delete it), you need to edit the \{MAILSERVER}\Declude\$default$.JunkMail file. This file has one line for each test that will be run. Each line has the name of the test, followed by the action to take. For example, a line that says "ORBZ WARN" means that Declude JunkMail will add a warning to the headers of the E-mail if it fails the ORBZ test.

If you wanted to have Declude JunkMail hold E-mails that is listed in ORBZ, you would change the line "ORBZ WARN" to "ORBZ HOLD". A list of the various actions that can be taken are as follows later.

4. Actions

Actions are a very important concept with Declude JunkMail. See the "Basic Configuration" section for how to set up the actions. Note that the actions are listed here in order with the lowest priority tests listed first; this order will be used to determine what action is taken when an E-mail fails multiple tests. For example, if an E-mail fails two tests, one using the "HOLD" action, and the other using the "DELETE" action, the DELETE action will take priority.

The actions currently available are:

To: %MAILFROM%

From: postmaster@%LOCALHOST%

Subject: Deliverable mail

Your mail was delivered, but may not be read by the recipient

because it contains invalid headers that are not RFC compliant.

Original message follows:

%FULLMSG%

To: %MAILFROM%

From: postmaster@%LOCALHOST%

Subject: Undeliverable mail

Your mail was not delivered because it contains invalid headers

that are not RFC compliant.  Original message follows:

%FULLMSG%

5. Tests

Declude JunkMail comes with a variety of tests already defined for you. It is also possible to define new tests as they come out, or create tests of your own.

6. Advanced Configuration

[You only need to worry about this section if mail is NOT delivered directly to your {MAILSERVER}, or you want to fine-tune Declude JunkMail.]

6.1 Scanning different hops

Declude JunkMail is likely the only spam control program to allow you to work over multiple hops. This means that if E-mail isn't delivered directly to your {MAILSERVER} (for example, if the MX record for your domain points to a virus scanner, that then forwards to your {MAILSERVER}), you can still use Declude JunkMail! See the "Skipping your backup mail server or gateways" section for information on how to bypass your backup mail server or gateways.

If you have a set number of hops in front of your {MAILSERVER}, which you may not know the IPs of, the HOP option may be useful. When set to 0 (the default), Declude JunkMail uses the IP address of the mail server that connected to the {MAILSERVER}. If you set it to 1, Declude JunkMail will check the IP address 1 hop away. You would use this if you have 1 SMTP server before your {MAILSERVER}.

If you want to scan a range of hops, you can use the HOP option along with the HOPHIGH option. In this case, you would set HOP to the first hop that you want to scan, and HOPHIGH to the last hop that you want to scan. For example, if you want to scan the IP of the mail server that connected to yours, as well as the one that connected to it, you would set HOP to 0 and HOPHIGH to 1. Be aware that every hop you scan will require extra time for DNS checks.

Normally, you will leave the HOP setting at "HOP 0", and use an IPBYPASS line for each gateway or backup mail server.

6.2 Skipping your backup mail server or gateways

If you have a backup mail server, the normal E-mail routing can be changed. Rather than remote mail servers delivering mail directly to the primary mail server, the mail can sometimes go through the backup. In this case, Declude will by default scan the IP address of your backup server (since it doesn't know that it is your backup mail server).

Declude JunkMail can still work in this situation. To handle this, you can add a line to the \{MAILSERVER}\Declude\global.cfg file that says "IPBYPASS 192.0.2.25" (where 192.0.2.25 is your backup mail server). Using the IPBYPASS configuration option, Declude will skip over that hop, and automatically start scanning based on the IP of the mail server that connected to the backup mail server. You can have up to 20 IPBYPASS lines in the global.cfg file.

6.3 Acting as a gateway for domains on other servers

Declude JunkMail can be set up to scan E-mail for domains that are not hosted on your {MAILSERVER}. First, you need to set up your {MAILSERVER} to accept mail to the gateway domains and pass on the mail to the correct server (you need to set up the MX records to point to the {MAILSERVER}, and follow the instructions in the manual or {MAILSERVER} Knowledge Base for a gateway domain).

The only catch as far as Declude JunkMail is concerned is that {MAILSERVER} will treat the E-mail to the gateway domain as outgoing mail, since it is not stored on the {MAILSERVER}. Therefore, by default, the outgoing actions in the \{MAILSERVER}\Declude\global.cfg file will be used. To get around this, you can set up per-domain configuration files for the gateway domains.

6.4 DNS Server

By default, Declude JunkMail uses the same DNS server that {MAILSERVER} uses. If you want to use a different DNS server, you need a line in the configuration filestarting with "DNS", followed by the IP of your DNS server. For example, "DNS 198.6.1.2".

6.5 Adding headers to the E-mail:

Declude has several ways that you can add headers to the E-mail that it processes. The standard way is as an action, for example "ORBZ WARN" will add a warning to the headers if the E-mail comes from an IP address listed in the ORBZ spam database.

If you want to record the name of the sender (according to the SMTP Envelope) in the E-mail headers, you can use the XSENDER configuration option. To do this, add a line to the \{MAILSERVER}\Declude\global.cfg file that says "XSENDER ON".

If you want to log the spool file name of the E-mail in the headers, you can use the configuration option "XSPOOLNAME". Just add a line to the \{MAILSERVER}\Declude\global.cfg file that says "XSPOOLNAME ON". This is useful for finding the Declude log file entry for an E-mail.

To add a header to all incoming E-mail or all outgoing E-mail, you can use the XINHEADER and XOUTHEADER configuration options. See the "variables" section for a list of the variables you can use. For example, you can add a line in \{MAILSERVER}\Declude\global.cfg that says "XOUTHEADER X-Note: Please send abuse reports to abuse@%LOCALHOST%.". Note that this will appear on all E-mail, whether or not any tests are run or actions are taken.

6.6 Hiding tests from the X-Spam-Tests-Failed: header

Declude JunkMail has a HIDETESTS option that lets you specify tests that should not be listed in the X-Spam-Tests-Failed: header. This is useful for tests that are not indicative of spam (such as the CATCHALLMAILS test, which all E-mails will trigger). To use this option, just list any such tests in the HIDETESTS line in the
\{MAILSERVER}\Declude\global.cfg file (for example, "HIDETESTS CATCHALLMAILS IPNOTINMX OLEGITCONTENT").

6.7 Whitelisting mail

If you need to whitelist mail (make sure that it passes all the spam tests), you can do so, based on the IP address, the return address, or text that appears within the E-mail.

WARNING: White listing is a last resort to accept mail from poorly administered mail servers, and will often allow spam through if you are not careful. For example, "WHITELIST FROM @hotmail.com" will allow a LOT of spam through, "WHITELIST FROM mail.com" would whitelist mail from mail.com and hotmail.com, and you should never use "WHITELIST FROM your_domain.com" (since many spammers will use a made-up return address on your domain). If you do not understand these warnings, you should not use whitelists.

To whitelist an IP address, add a line "WHITELIST IP 127.0.0.1" to the \{MAILSERVER}\Declude\global.cfg file (replacing 127.0.0.1 with the IP you wish to whitelist). If you wish to whitelist a range of IP addresses, such as 127.0.0.0 through 127.0.0.255, you can do so by adding a line "WHITELIST IP 127.0.0." (which will whitelist any E-mails from mail servers with an IP address that contains "127.0.0."). You can also use a CIDR range, such as "WHITELIST IP 127.0.0.0/8" or "WHITELIST IP 192.0.2.0/24" (see the DNSstuff.com site's CIDR tool for assistance).

To whitelist an E-mail address, add a line "WHITELIST FROM user@example.com" to the \{MAILSERVER}\Declude\global.cfg file (replacing user@example.com with the address you wish to whitelist). You can also whitelist all mail from a specific domain by using "WHITELIST FROM @example.com" (you can whitelist a single subdomain with "WHITELIST FROM @subdomain.example.com", or all subdomains with "WHITELIST FROM .example.com"). Note that "WHITELIST FROM" will whitelist a return address (like {MAILSERVER} does in the Kill List), which may be different from the From: or Reply-To: addresses. You need to look at the X-Declude-Sender: header (if you use the XSENDER ON option) or the "MAIL FROM:" line in the {MAILSERVER} SMTP log file to find the return address.

You can whitelist text that appears anywhere in the headers or body of the E-mail, by using "WHITELIST ANYWHERE text" (replacing "text" with the text you wish to use for whitelisting). For example, you could use "WHITELIST ANYWHERE The secret code is 12345", and any E-mail containing "The secret code is 12345" would be whitelisted.

To whitelist mail TO a certain domain, you can use "WHITELIST TODOMAIN @example.com". You can also whitelist mail to specific users, by using "WHITELIST TO user@example.com". You do not need to enter domain aliases if do not want to (for example, if you have the domain name as "example.com" with "mail.example.com" as an alias, you only have to enter "WHITELIST TODOMAIN @example.com").

Finally, you can whitelist E-mail with the "Habeas Headers", by adding a line "WHITELIST HABEAS". The Habeas headers will appear in legitimate E-mail from sources that are approved to use the headers. Any spammers that get whitelisted due to the Habeas headers can be reported to www.habeas.com, and legal action will likely be taken against them. This is a good way to help prevent false positives -- people whose E-mail gets caught as spam can just go to the URL shown to find out how to add the Habeas headers to their E-mail.

You can have up to 200 of the WHITELIST entries in the global.cfg file. They only work in the global.cfg file; you can not have user-specific or domain-specific whitelists. Also, they work on a "partial match", so you should not remove the "@" from E-mail addresses (or domains) that you whitelist, without thinking of the consequences. To see all the available WHITELIST options, you can look at the Whitelist/Blacklist Reference section of the manual.

6.7.1 Automatic Whitelisting

With Declude JunkMail Pro, you can automatically whitelist E-mail addresses that are listed in the recipient's address book. To do this, you just need to add a line "AUTOWHITELIST ON" to your \{MAILSERVER}\Declude\global.cfg file (or if there is already a line "AUTOWHITELIST OFF", you can change it to "AUTOWHITELIST ON").

With this feature enabled, when an E-mail is received, Declude JunkMail will check to see if the sender is listed in the recipient's web messaging address book. If so, the E-mail will automatically be whitelisted. This feature can help reduce false positives.

6.7.2 Whitelist Files

If you need to have unlimited whitelist entries, or if you need per-user or per-domain whitelisting, you may find the WHITELISTFILE option helpful.

To use this option, you need to add a line in the format "WHITELISTFILE D:\{MAILSERVER}\Declude\mywhitelist.txt" to the appropriate configuration file (\{MAILSERVER}\Declude\$default$.JunkMail, or the per-user/per-domain configuration file you wish to use the whitelists with). The D:\{MAILSERVER}\Declude\mywhitelist.txt file would then contain either one E-mail address ("user@example.com") or domain ("@example.com") or subdomain (".example.com") per line. The whitelist files can have unlimited entries in them.

Note that the file you use with the WHITELISTFILE option does NOT use the same format as the WHITELIST entries in the global.cfg file. Also, note that the WHITELISTFILE option does not work in the global.cfg file.

6.7.3 Whitelisting Authenticated Users

If you are using IMail v8, you can use a line "WHITELIST AUTH" in your \IMail\Declude\global.cfg file to automatically whitelist your own users that authenticate. This is useful to help ensure that the E-mail your users send does not get caught, especially if they are using a mail client such as Outlook that may fail several anti-spam tests.

6.8 Your own IP blacklists

With Declude JunkMail Standard and Declude JunkMail Pro, you can add your own IP blacklist (a list of IP addresses that you will treat differently -- that you delete, bounce, add a warning to the headers of, etc.).

First, you need to create a text file that lists one IP address per line, followed by the reason for blocking it. For example, "127.0.0.1 This is a test block".

Next, you need to define a new Declude JunkMail test. In the \{MAILSERVER}\Declude\global.cfg file, you can add a line "TESTNAME ipfile C:\{MAILSERVER}\Declude\ipfile.txt x 5 0" (where "TESTNAME" is the name of your new test, followed by the word "ipfile" (which is the test type), followed by the name of the file you have the IPs listed in, "x" as a placeholder, followed by the weight (5) and a 0).

Once you have defined the blacklist, you can use whatever actions you would like in the configuration files (per-user, per-domain, or default, just like the other tests).

You can define as many different IP blacklists as you like, so you could, for example, have a list of IPs that you will not accept mail from, and another that would just result in a warning in the headers.

To blacklist a range of IPs, you can use CIDR style IP ranges. For example, "127.0.0.0/8" would blacklist all addresses from 127.0.0.0 through 127.255.255.255. "127.0.0.0/24" would blacklist the Class C range from 127.0.0.0 through 127.0.0.255. For assistance on CIDR ranges, you can use the CIDR tool at the DNSstuff.com site

6.9 Your own sender blacklists

With Declude JunkMail Standard and Declude JunkMail Pro, you can add your own sender blacklist (a list of return addresses or domains that you will treat differently -- that you delete, bounce, add a warning to the headers of, etc.). This works on the return address (where bounce messages would be sent, as seen in the X-Declude-Sender: header), which may be different from the "From:" address in the headers. Note that the return address is not visible in the headers unless you use the "XSENDER ON" option (you can later find out what the return address was by checking the {MAILSERVER} SMTP log files for the "MAIL FROM:" line).

First, you need to create a text file that lists one address or domain per line, followed by the reason for blocking it. For example, "@example.com This domain sends spam." or "evilperson@hotmail.com This guy was mailbombing us". To block a domain, you can either use the format "@example.com" to block just example.com, or you can use just "example.com" which would block mail from "user@example.com", "user@mail.example.com", and even "user@another_example.com".

Next, you need to define a new Declude JunkMail test. In the \{MAILSERVER}\Declude\global.cfg file, you can add a line:

        TESTNAME fromfile C:\{MAILSERVER}\Declude\badaddresses.txt x 5 0

(where "TESTNAME" is the name of your new test, followed by the test type ("fromfile"), followed by the name of the file you have the addresses and/or domains listed in, followed by a placeholder, and the two weights for the test).

Once you have defined the blacklist, you can use whatever actions you would like in the configuration files (per-user, per-domain, or default, just like the other tests).

You can define as many different sender blacklists as you like.

6.10 Test Definitions

Tests are defined in the \{MAILSERVER}\Declude\global.cfg file. The format of a test definition is the name of the test, followed by the test type, followed by two test-specific pieces of information, followed by two weights: The weight that will be assigned to the test if an E-mail fails the test, and the weight that will be assigned if the E-mail does not fail the test (normally 0).

For example, the ORDB test might be defined as "ORDB ip4r relays.ordb.org 127.0.0.2 5 0". This would mean that the test named ORDB is an "ip4r" test type (for "dnsbl" style DNS lookups), using the zone relays.ordb.org, and looking for a result of 127.0.0.2. If an E-mail fails the test, the test would have a weight of 5; otherwise, it would have a weight of zero.

6.11 Multiple actions per test

Declude JunkMail does not support multiple actions per test. When it was designed, it was assumed that people would only want to use one of the two actions that other anti-spam products use: WARN or BOUNCEONLYIFYOUMUST.

However, since Declude JunkMail allows so many different actions to be taken on E-mail, a number of people have requested the ability to use multiple actions per test. Although Declude JunkMail does not support this, there is a way to accomplish the same end result. You just need to define two copies of the same test, each with a different name.

For example, if you wanted to have the SPAMCOP test use both the WARN and SUBJECT actions, you would change add a new test SPAMCOP2. The \{MAILSERVER}\Declude\global.cfg defines the SPAMCOP test as:

SPAMCOP ip4r bl.spamcop.net 127.0.0.2 7 0

You would add another entry that is identical except with a different name, so you would now have:

SPAMCOP ip4r bl.spamcop.net 127.0.0.2 7 0
SPAMCOP2 ip4r bl.spamcop.net 127.0.0.2 0 0

Then, in your $default$.JunkMail file, you could have:

SPAMCOP SUBJECT Spam:
SPAMCOP2 WARN

Now, both actions will be used. There are some combinations of actions that will not work together (such as DELETE and HOLD, which logically can't both be used), but most will. Also, if you use the weighting system, you should set the weights of the second test to 0, so that you do not end up with double the weight.

6.12 "Copy All" account

If you have a "Copy All" account set up in {MAILSERVER} (such that all E-mail is copied to a specific mail account), and use Declude JunkMail Pro, you should set up a per-user setting for that account (with the actions set to IGNORE). Otherwise, your per-user settings may not work as expected.

6.13 External Tests

Declude JunkMail supports external tests -- tests that use third-party spam detection programs (such as Message Sniffer, or your own custom programs).

Your program will get called by Declude JunkMail, with the name of the spool file containing the E-mail as a parameter ("yourfile.exe c:\{MAILSERVER}\spool\D1234567.SMD", for example). The file contains the complete E-mail, including headers and body. Your program should only read this file, not write to it.

After your program is finished, it needs to return an exit code to Declude JunkMail (in C/C++, this is done simply with "return code;" at the end of the main function; you can (carefully!) use the Windows ExitProcess( ) function in other languages).

To define the test, you need a line in the format 'TESTNAME external returnvalue "filename"'. TESTNAME is the name of your test, "returnvalue" is the code your program will return when it detects spam (or "nonzero" for any code other than zero), and the name of your file needs to be in quotes. You can add weights, by adding two numbers at the end of the line: the first one is the standard weight (the weight if the test fails), the second is the "negative weight" (the weight if the test does not fail, usually 0). The test will then work in Declude JunkMail just like any other test.

For more flexibility, you can have Declude JunkMail pass parameters to your program, using variables. For example, you can set up the test as 'TESTNAME external returnvalue "filename %INOROUT%"', which would send the %INOROUT% variable as a parameter to your program (which would be "incoming" for an incoming E-mail, or "outgoing" for an outgoing E-mail).

6.13.1 External tests - whitelisting E-mail

An external test can whitelist E-mail by using the "externalplus" test type. With the externalplus test type (using a test definition such as 'MYTEST externalplus nonzero "C:\{MAILSERVER}\Declude\myprog.exe"'), you can return 0 if an E-mail is not considered spam, 1 if it should be whitelisted, or a value of 10 or higher if the E-mail is considered spam. Note that return values of 2 through 9 are reserved for future use.

6.13.2 External tests - returning a weight

An external test can return a weight by using "weight" in the test definition instead of the exit code that it will be returning. So you would use a format such as 'TESTNAME external weight "filename"'.

6.14 Using the actual recipient instead of intended recipient for settings.

{MAILSERVER} will report two addresses for each recipient of an E-mail, the "Intended recipient" (the one that the E-mail was addressed to), and the "Actual recipient" (the address after aliases have been accounted for). The configuration files in Declude JunkMail are based on the actual recipient. If for some reason you would like to override this behavior (and have the configuration files based on the intended recipient), you can add a line "SWITCHRECIP ON" to the \{MAILSERVER}\Declude\global.cfg file. However, this is not normally recommended.

7. Weighting System

Declude JunkMail has a weighting system, designed to improve spam detection while minimizing false positives. It accomplishes this by assigning a weight to each test, and calculating the total weight of all tests that fail. For example, if the MAILFROM test is given a weight of 5 and the REVDNS test is given a weight of 7, an E-mail failing both tests would have a total weight of 12. The higher the weight, the more likely an E-mail is to be spam.

The default configuration files include weighting information, along with a WEIGHT10 test (which is set up to be triggered if the total weight of the E-mail is 10 or greater) and a WEIGHT20 test (which gets triggered if the total weight of the E-mail is 20 or higher).

You can add your own weight level to look for by adding a line such as "WEIGHT15 weight x x 15 0" to define a new WEIGHT15 test in the \{MAILSERVER}\Declude\global.cfg file. You could then add a line "WEIGHT15 HOLD" to the \{MAILSERVER}\Declude\$default$.JunkMail file, which would hold any E-mail with a total weight greater than or equal to 15.

To change the weight of a specific test in Declude JunkMail, see the "Test Definitions" section.

7.1 Weight Ranges

For more advanced usage, you can define a test that will only get triggered when a certain range of weights is reached. For example, you can have a test that will only get triggered when the total weight of the E-mail is between 10 and 20.

You can define a weight range test by adding a line in the format "WEIGHT1020 weightrange x x 10 20" (the name of the test, followed by "weightrange", two placeholders, and the low weight and high weight).

This will catch any E-mail with a total weight in a range between and including 10 and 20.

7.2 Exact Weights

To catch a single weight, such as only E-mail with a weight of 10, you can use the "weightmatch" test type, by defining a test such as "WEIGHT10EXACT weightmatch x x 10 0". This will catch mail with a total weight of exactly 10 (but not catch any E-mail with a weight of less than 10, or more than 10).

8. Filtering

Declude JunkMail Pro allows you to create your own filters. The Declude JunkMail filters, you can have the filters count towards the weighting system, and you can use actions of your choice. Warning: Filters (in Declude, IMail, SmarterMail, or anywhere else) can be very dangerous if you are not careful. For example, filtering for swear words can catch unrelated words, such as "assassin", "document", "chardonnay", "Mr. Hitchcock", etc.

First, you need to define the test. To do this, add a line to the \{MAILSERVER}\Declude\global.cfg file in the format "MYFILTER filter C:\{MAILSERVER}\Declude\myfilter.txt x 5 0". This will define a test named MYFILTER, that will be a filter using your filter file at C:\{MAILSERVER}\Declude\myfilter.txt. A weight of 5 will be added to every E-mail that is caught by your filter.

Then, you need to create the filter file (myfilter.txt in the example above). Each line contains one filter, in the format "location weight filtertype filtertext", where "location" is where the filter will be looking (this can be BODY, HEADERS, HELO, MAILFROM, REMOTEIP, REVDNS, ALLRECIPS, ANYWHERE, TESTSFAILED, or SUBJECT), "weight" is the weight to add to the E-mail if the filter matches (normally 0), "filtertype" can be "CONTAINS", "STARTSWITH", "ENDSWITH", "NOTCONTAINS", "NOTENDSWITH", "NOTIS", "CIDR", or "IS," and "filtertext" is the text to look for (case insensitive, so "hello" will match both "hello" and "hELLo"). For example:

        HELO     8   CONTAINS    localhost

        SUBJECT  3   CONTAINS    enlarge

        MAILFROM 3   STARTSWITH  $$$success$$$@

        BODY     3   CONTAINS    To unsubscribe, click here

The first one would look for HELO/EHLO text that contains "localhost" in it (and if it does, a weight of 8 will be added to the weight of the E-mail), the second one would look for an E-mail that contains "enlarge" in it and add 3 to the weight of the E-mail, and the last one would look for a return address beginning with "$$$success$$$@" (and add 3 to the weight of the E-mail if there is a match).

Note that the weights are in addition to whatever action you have set for the test, so if you have:

MYFILTER WARN X-Warning: This E-mail was filtered.
WEIGHT10 HOLD

in the \{MAILSERVER}\Declude\$default$.JunkMail, an E-mail with "$domain" in the HELO/EHLO text would be held and have a warning in the headers, and be held (since the MYFILTER test was defined to have a weight of 5, and the "$domain" in the HELO/EHLO added 8 to the weight).

You can also use negative weights, such as:

REVDNS -5 CONTAINS yahoo.com
There is no limit to the number of lines in a filter file.

8.1 Advanced Filtering Options

There are several options to help save CPU usage if you have lots of filters. One option is STOPATFIRSTHIT (a line with just "STOPATFIRSTHIT" in the filter file), which instructs Declude JunkMail to stop the processing of the filter as soon as the first hit occurs in the filter. There is another option SKIPIFWEIGHT that will instruct Declude JunkMail to skip the test if a certain weight is reached (either when the test is run, or at any point during processing) -- to use this, just add a line in the format "SKIPIFWEIGHT 20" to the filter file (where 20 is the weight to stop processing at). Finally, you can use "END" in place of the weight to stop processing of the test at that point (for example, "BODY END CONTAINS password")
.
If you want to stop all further filters (not just the current filter), you can use the STOPALLTESTS option in place of the weight. For example, "BODY STOPALLTESTS CONTAINS Evil Spammer" would prevent further processing of this filter or any other filters after it.

Another useful option is the WHITELIST option, which can be used instead of the weight. For example, you can have a line "SUBJECT WHITELIST CONTAINS password" to automatically whitelist any E-mails containing the word "password" in the subject.

Finally, there are some other weight-related options. There is a MINWEIGHTTOFAIL option that will instruct Declude JunkMail not to trigger the test unless a minimum weight is reached (for example, "MINWEIGHTTOFAIL 4" would require that the filter add at least 4 points to the weight of the E-mail in order for the test to be triggered). You can also use MINWEIGHT and MAXWEIGHT to specify minimum and/or maximum weights that the test can add. For example, "MAXWEIGHT 20" would make sure that the filter did not add more than 20 points to the weight of the E-mail.

9. Theory

Declude JunkMail intercepts all E-mail between the point at which it is received, and the point at which {MAILSERVER} delivers it. This way, Declude JunkMail catches all E-mail that goes through the {MAILSERVER}.

Declude JunkMail then runs the message through a variety of tests. All of the tests are defined in the configuration file, so if you do not want a test run, you can take it out of the configuration file.

The most popular (and debated!) tests are the ip4r category of tests (RBL, ORDB, etc.). These work by taking the IP address of the machine that connected to {MAILSERVER}, reversing the order, and running a DNS lookup on a specific domain. If the DNS A record exists and matches a certain string, the E-mail fails the test (and is considered spam).

For each test, you can determine what action will be taken on the E-mail. For example, you can have any E-mail that fails the SPAMCOP test (which rarely lets legitimate E-mail through) held in the "spam" directory so that you can later check the messages to verify that they are spam. You could then have E-mail that fails the ORDB test (which often lets legitimate E-mail through) just have a warning message added to the headers.

In the case that an E-mail fails 2 or more tests, the stricter action will be taken. In the above example, if a message failed the ORDB test and the SPAMCOP test, it would be held in the "spam" directory.

9.1 Processing Order for IMail

Both IMail and Declude have a number of different tests that they run on E-mail. The order used is as follows:

1. IMail’s Control Access file (to block IPs)

2. IMail’s Kill List (to block return addresses)

3. IMail v8 anti-spam (most tests)

4. Declude Virus

5. Declude Hijack

6. Declude JunkMail

7. IMail's filters and extra IMail v8 anti-spam tests

With versions before v1.68, Declude Hijack would be run before Declude Virus and Declude JunkMail. If using the AVAFTERJM option in Declude Virus, Declude Virus will run after Declude JunkMail.

10. Testing

10.1 Making sure Declude JunkMail is really monitoring your E-mail:
If you kept the default LOGLEVEL setting at LOW, Declude JunkMail will place one entry into the \{MAILSERVER}\spool\dec####.log file for every incoming message that does not fail any tests. If there is not an entry in there for every incoming message (and LOGLEVEL is set to LOW, MID, HIGH, or DEBUG), something is not set up properly -- please contact support@declude.com. When a message DOES fail, you will see an entry "Msg failed ORDB" (or whatever the name of the test was). This message may not appear if you changed the settings of the test to IGNORE.

10.2 Making E-mail fail a test
There are two ways to do this. First, you can send an E-mail to an account at your domain where the first line starts with "rsp set off ", and then has the name of a test. For example, "rsp set off ORDB" will trigger the ORDB test. Note that the test name is CASE SENSITIVE (ORDB not ordb). This ONLY will work if your E-mail client does NOT send HTML (which places other lines before the "rsp set off" line).

The other way to make an E-mail fail a test is to use an autoresponder set up to do so. You can find some at http://www.crynwr.com/spam/, but these only work if you subscribe to the www.mail-abuse.org tests. You send an E-mail to one address; one reply should PASS Declude JunkMail's tests, the other one should FAIL one of the tests. Note that the E-mail you get back will be VERY MISLEADING, saying that it didn't work, whether or not it did. Also note that RBL, RSS, and DUL now require a SUBSCRIPTION (see http://www.mail-abuse.org).

11. Per-Domain Configuration

Declude JunkMail allow you to have different settings for each domain that you have. These will let you have different actions for each domain.

In order to do this, you first need to create a subdirectory off of the Declude directory, with the same name as the domain you wish to change. For example, to add a per-domain configuration for "example.com", you would create the directory \{MAILSERVER}\Declude\example.com. Note that this needs to be the official domain name, not a domain alias (so if you have a domain "mail.example.com" with "example.com" as an alias, the directory should be "\{MAILSERVER}\Declude\mail.example.com\"). The exception is that if you have a user alias, the domain you use in the alias will take priority (for example, if the alias is "sales" that points to "salesman@example.com", you would need to use the directory "example.com").

It may be necessary to use two different directories, if you have users aliases pointing to domain aliases (a quirk in IMail).

The next step is to copy the $default$.JunkMail file into that directory. Then, edit that file to reflect the settings you want for that domain.

Or, to quickly disable spam control for a specific domain, you can whitelist all mail to the domain by using the "WHITELIST TODOMAIN @example.com" setting in the global.cfg file.

Note that you should not delete the \{MAILSERVER}\Declude\$default$.JunkMail file. If that file does not exist, there will be no default settings for E-mail addressed to domains that do not have their own per-domain settings.

11.1 Redirecting (groups)

Another way for you to use per-domain configurations is by using redirecting, or groups. The REDIRECT command in a config file will instruct Declude JunkMail to use a different configuration file for a specific user or domain.

To use this, the \{MAILSERVER}\Declude\$default$.JunkMail (or any of the per-user or per-domain config files) can have a line in the format "REDIRECT @example.com C:\{MAILSERVER}\Declude\filename.cfg". When Declude JunkMail sees this line, if it is processing mail to @example.com, Declude JunkMail will instead use the C:\{MAILSERVER}\Declude\filename.cfg file for determining the action to take on the E-mail.

Note that while this option can be used in any of the Declude JunkMail configuration files, it will only be used in whatever configuration file that Declude JunkMail is using for an E-mail. For example, if you have a REDIRECT line in the \{MAILSERVER}\Declude\example.com\$default$.JunkMail file, Declude JunkMail won't use it for an E-mail to user@example.NET.

12. Per-User Configuration

Declude JunkMail Pro allows you to have different settings for each user on your system. These will allow you to have different actions for each user.

First, you need to create a subdirectory off of \{MAILSERVER}\Declude for the domain the user is on (if the directory doesn't yet exist). For example, if you want per-user settings for "myname@example.com", you would create the directory \{MAILSERVER}\Declude\example.com.

Next, copy the \{MAILSERVER}\Declude\$default$.JunkMail into this directory, and rename it to the users' name followed by ".JunkMail" (be sure not to overwrite the existing $default$.JunkMail file in this directory, if there is one -- it is the per-domain configuration file). For example, if you want a separate configuration for "john.doe@example.com", you would copy the $default$.JunkMail file to \{MAILSERVER}\Declude\example.com\john.doe.JunkMail

Then, edit that file to reflect the settings you want for that user.

Or, to quickly disable spam control for a specific user, you can whitelist all their E-mail by using the "WHITELIST TO user@example.com" setting in the global.cfg file.

Note that you should not delete the \{MAILSERVER}\Declude\$default$.JunkMail file. If that file does not exist, there will be no default settings for E-mail addressed to domains or users that do not have their own settings.

12.1 Redirecting (groups)

Another way for you to use per-user configurations is by using redirecting, or groups. The REDIRECT command in a config file will instruct Declude JunkMail to use a different configuration file for a specific user.

To use this, the \{MAILSERVER}\Declude\$default$.JunkMail (or any of the per-user or per-domain config files) can have a line in the format "REDIRECT user@example.com C:\{MAILSERVER}\Declude\filename.cfg". When Declude JunkMail sees this line, if it is processing mail to user@example.com, Declude JunkMail will instead use the C:\{MAILSERVER}\Declude\filename.cfg file for determining the action to take on the E-mail.

Note that while this option can be used in any of the Declude JunkMail configuration files, it will only be used in whatever configuration file that Declude JunkMail is using for an E-mail. For example, if you have a REDIRECT line in the \{MAILSERVER}\Declude\example.com\$default$.JunkMail file, Declude JunkMail won't use it for an E-mail to user@example.NET.

13. Log File

By default, Declude JunkMail will record at least one entry to the log file for each E-mail that is received. The log file location is determined by the LOGFILE option in the \{MAILSERVER}\Declude\global.cfg file. To change the location of the log file, look for the line that begins with "LOGFILE", and you can change the name of the log file there.

If you do not want Declude JunkMail to record to the log file any E-mail that is not spam, you can add a line "LOG_OK NONE" to the \{MAILSERVER}\Declude\global.cfg file.

You can also change the level of logging, using the LOGLEVEL option: LOGLEVEL ERROR will only record error messages (not recommended), WARNING will also record warning messages, LOW to report basic information about each message, MID to report slightly more information, HIGH to report a lot of information, or DEBUG to report thorough diagnostic messages (this should normally only be used at the request of our support department).

The most common log file entries are "Message OK" (which appears if the E-mail does not fail any spam tests), and "Msg failed TESTNAME" (you will see one line for each spam test that the E-mail failed).

14. Variables

Declude has a number of "variables" that can be used in the configuration files. These variables will be replaced with certain information; for example, if Declude sees "%REMOTEIP%" in a warning header, it will replace it with the IP address of the remote mail server. These can be used with certain actions (WARN, SUBJECT, HEADER, FOOTER), and in "bounce" messages.

15. Whitelist/Blacklist Reference

Note that other formats will not work; for example, using a "*" or "-" in an IP address will not work.

16. FAQ + Troubleshooting

16.1 How can I catch more spam?

• Make sure that Declude JunkMail knows about any backup mail servers or gateways that may send mail to your {MAILSERVER}. You should have an "IPBYPASS" line in your \{MAILSERVER}\Declude\global.cfg file for each backup mail server or gateway.
  
• Make sure that you do not have any whitelists that will allow a lot of spam through. The #1 problem with whitelisting is that people whitelist E-mail from their own domain. However, many spammers will send mail with a return address on the same domain that they are sending to, so you should not whitelist E-mail from your domain. Also, note that "WHITELIST FROM mail.com" will whitelist all E-mail from @hotmail.com (since it contains "mail.com"); instead, you would want to use "WHITELIST FROM @mail.com".
  
• Make sure that you remove any dead spam tests from your \{MAILSERVER}\Declude\global.cfg file, and check with the latest global.cfg file (see the "Installation" section at the top of this page to download it) to see if there are new spam tests to use.

16.2 NO spam is getting caught, why?

If you just installed Declude JunkMail, the default settings will only add a standard X-RBL-Warning: header (the WARN action) when spam is detected. If you want to quickly start blocking some spam, you may want to try changing the "WEIGHT20 WARN" line in the \{MAILSERVER}\Declude\$default$.JunkMail file to "WEIGHT20 HOLD".

16.3 I don't think that Declude JunkMail is working with IMail, what should I do?

First, make sure that the \IMail\Declude\global.cfg file exists (and is named "global.cfg"), and has your activation code in it. Stop/Restart the decludeproc service This will create a diagnostic file called diag.txt located in the \Declude folder that you can send to support@declude.com for assistance.

16.4 Lots of legitimate mail is being caught, why?

Most likely, you set up all or many of the spam tests to use the HOLD or DELETE action. All spam tests have flaws, and many of the spam tests are not designed to catch spam alone (but work well towards the weighting system). For example, lots of legitimate mail from poorly designed web servers will fail the SPAMHEADERS test. You should make sure to only use tests that you understand. Rather than blocking mail that fails individual tests, we recommend blocking mail that fails the WEIGHT20 test (or WEIGHT10 test, if you can a bit of legitimate E-mail getting caught in exchange for more spam caught).

16.5 Why didn't Declude JunkMail add the weights correctly?

Often, a customer will see that an E-mail failed certain spam tests, but has a weight lower than what they expect. For example, if an E-mail fails just the SPAMCOP test (which has a weight of 7 points), the total weight of the E-mail may be 4. This will occur if the E-mail did not fail certain tests that are set up with a negative weight. For example, the IPNOTINMX and NOLEGITCONTENT tests are designed to help legitimate E-mail rather than hurt spam. As a result, E-mails that fail those tests will have not have any points added to them, but E-mails that do not fail them will have points subtracted from their total weight.

16.6 Why did this E-mail get marked as spam (or deleted)?

This is a question we often receive, and since we often can't easily answer the question, we felt it would be a good idea to have a section about this in the manual.

If an E-mail is marked as spam (if it is held in the \{MAILSERVER}\spool\spam directory, for example), it is because it failed one or more spam tests. So the real question is "What tests did the E-mail fail?".

The easiest way to find out is to have a line (in your \{MAILSERVER}\Declude\global.cfg file) that says "XINHEADER X-Spam-Tests-Failed: %TESTSFAILED%.". This will place a header in the E-mail that lists the tests that failed, making it easy to determine which test(s) failed.

The other way to find out is to look at the Declude JunkMail log file. If you use the "XSPOOLNAME ON" option in the \{MAILSERVER}\Declude\global.cfg file, it will be easy to find the entries for the E-mail in the log file. If you do not use the XSPOOLNAME ON option, you may need to look at the {MAILSERVER} SMTP log file to file the queue file name of the E-mail, and search the Declude JunkMail log file for it (minus the first character and extension; for example, if you see "Q1234567.SMD" in the {MAILSERVER} log, you would search the Declude JunkMail log for "1234567").

Now that you have found the E-mail in the log file, you know which test(s) it failed.

16.7 Why did this E-mail NOT get marked as spam?

There are three common reasons for this:

• The E-mail didn't fail any spam tests,
• The E-mail failed spam test(s), but the actions you are using for those spam tests did not mark the E-mail as spam (for example, if you use the WARN action, the spam will be delivered and will seem like normal E-mail to many E-mail clients).
• The E-mail was whitelisted. If you have any WHITELIST entries in your \{MAILSERVER}\Declude\global.cfg file, you'll need to check them all to see if they could have whitelisted the E-mail. Remember, whitelisting is a last resort.

16.8 Why did an E-mail fail the SPAMHEADERS test?

To find out, you need to find the code that Declude JunkMail assigned the E-mail (such as "40000202"). If you use the WARN action, this will appear in the E-mail headers. Otherwise, you will need to look in the log file.

You can look up the code using the "BADHEADERS lookup" at www.declude.com/tools . The most common reason an E-mail will fail the SPAMHEADERS test is because it is missing a Message-ID: header. The Message-ID: is not required in order for an E-mail to be valid, but the RFCs say that it "SHOULD" be there. "SHOULD" in RFC terminology means that the header must be there *unless* there is a good reason for it not to be there, and the consequences of it not being there are known. I can't think of a good reason for the Message-ID: header not to be present (except that it saves programming time). The consequences of not having a Message-ID: header is that the mail may or may not be delivered if it is missing.

FYI, IMail does add a Message-ID: header if there isn't one already (since IMail knows the importance of the header). So, even though you see one, it was added by IMail. The problem can usually be fixed by upgrading the software used to send the E-mail.

16.9 Why did an E-mail fail the BADHEADERS test?

To find out, you need to find the code that Declude JunkMail assigned the E-mail (such as "80200202"). If you use the WARN action, this will appear in the E-mail headers. Otherwise, you will need to look in the log file.

You can look up the code using the "BADHEADERS lookup" at www.declude.com/tools . The most common reason an E-mail will fail the BADHEADERS test is because it is missing a Date: header (or has no time zone or an incorrect time zone). This is illegal, and will often cause E-mail to get "lost" on a server or mail client. Upgrading the software sending the E-mail will take care of the problem in almost all cases.

16.10 If spam gets held in the \IMail\spool\spam directory, how can I get it delivered?

IMail stores E-mails in two separate files, that both have the same name except that one begins with a "D" (which contains the actual E-mail), and one begins with a "Q" (which contains other information about the E-mail). You need to copy both of those files (for example, "Q1234567.SMD" and "D1234567.SMD") back to the spool directory. The E-mail will get delivered automatically on the next queue run (for faster delivery, you can use "Send One" from "View Queue" in the IMail Administrator).

16.11 Will gateway (store-and-forward) domains get scanned?

Yes. However, the {MAILSERVER} treats those domains as outgoing E-mail, since they are not stored locally. Therefore, the outgoing actions (from the \{MAILSERVER}\Declude\global.cfg file) will be used. If you want to use different actions for the gateway domains, you can set up per-domain settings for the domain.

16.12 The per-user (or per-domain) settings are not working

The most likely reason for this is that the directory you are using for the per-user or per-domain settings does not match the "real" domain name. For each domain, {MAILSERVER} has one "real" domain name and sometimes one or more aliases. If you have a domain listed in {MAILSERVER} as "host.example.com" with "example.com" as an alias, the per-user and per-domain settings should be in the \{MAILSERVER}\Declude\host.example.com\ directory, not the \{MAILSERVER}\Declude\example.com\ directory. Also, if a user alias is used, the account that it points to is used for the per-user settings.

16.13 Blacklisting is not working

The "fromfile" type of blacklisting checks the domain name or E-mail address that is in the "return address" (where bounce messages go; this is also the "MAIL FROM" in the SMTP envelope). This may be different than the "From:" or "Reply-To:" headers in the E-mail. If you use the "XSENDER ON" option, this address will appear in the X-Declude-Sender: header of the E-mail. Otherwise, you will need to look at the "MAIL FROM" line in the {MAILSERVER} SMTP log file to find this address.

16.14 Whitelisting is not working

The "WHITELIST FROM" type of whitelisting checks the domain name or E-mail address that is in the "return address" (where bounce messages go; this is also the "MAIL FROM" in the SMTP envelope). This may be different than the "From:" or "Reply-To:" headers in the E-mail. If you use the "XSENDER ON" option, this address will appear in the X-Declude-Sender: header of the E-mail. Otherwise, you will need to look at the "MAIL FROM" line in the {MAILSERVER} SMTP log file to find this address.

16.15 The wrong action is taken on E-mail

If you find that the wrong action is being taken on an E-mail (for example, if you see an X-RBL-Warning: header for a specific test, but you thought that E-mail failing that test should be held instead), the most likely problem is that Declude JunkMail is not using the configuration file that you thought it would use. You can use "LOGLEVEL HIGH" (in the \{MAILSERVER}\Declude\global.cfg file) to help here, as Declude JunkMail will report to the log file which configuration file it is using.

16.16 What version of Declude JunkMail am I running?

To find out, you can type "\{MAILSERVER}\Decludeproc -v" from a command prompt.

16.17 Can I run Declude Virus or Declude Hijack with Declude JunkMail?

Yes. All of the Declude programs can run together on the same server. Many of our customers run multiple Declude programs on the same server.

17. Help, Declude on IMail stopped working!

This may happen after an upgrade of IMail, which may overwrite the registry entry that Declude uses. To fix the problem, goto Imail Administrator --> SMTP --> Advanced --> Delivery Application and ensure that the executable is declude.exe then stop/restart the IMail SMTP service (so it recognizes the change).

Another rarer problem during an IMail upgrade (happening to about 5% of the 7.05 and 7.06 upgrades) is that the IMail upgrade may change the Official Host Name of your mailserver. To fix this, just change the Official Host Name ("Host Name" on the General tab of IMail Administrator, when "localhost" is highlighted on the left side of the screen) back to its original name.

18. Emergency Uninstall

18.1 How to uninstall Declude JunkMail (but leave Declude running)

To disable Declude JunkMail (but allow the core Declude code and other Declude programs you may have to continue running), simply rename the \{MAILSERVER}\Declude\global.cfg file to global.bak. This will prevent Declude JunkMail code from running, but will still allow the core Declude code to run.

18.2 How to uninstall Declude completely

IMAIL

Normally, you should never need to uninstall Declude. However, if you do need to, it is possible with one change in the registry (which will disable ALL Declude programs you may be running):

[1] Stop the IMail SMTP service
[2] Go to the Advanced tab in the SMTP settings in IMail Administrator, and change the "Delivery Application" option so that the part reading "declude.exe" is changed to "smtp32.exe" (for example, if it reads "C:\IMail \Declude.exe", change it to "C:\IMail \smtp32.exe"). If you are using an older version of IMail without that option, you will need to use regedit to change the HKEY_LOCAL_MACHINE\Software\Ipswitch\ IMail\Global\SendName key so that the part reading "declude.exe" is changed to "smtp32.exe"
[3] Restart the IMail SMTP service
[4] Copy any files from \ IMail \spool\proc to \ IMail \spool.

Next, check to make sure that incoming mail is delivered -- if not, check that registry key to make sure you didn't make a typo.

This will prevent Declude from scanning any messages. To let Declude scan messages again, just repeat the process, but change the "smtp32.exe" back to "Declude.exe", and stop/restart the IMail SMTP service.

SMARTERMAIL
Uncheck Declude under the anti-spam settings of SmarterMail.

19. Directives

19.1 Additional Directives

STOPPROCESSINGONFIRSTDELETE    ON - This setting will stop processing of the email if an action of DELETE was found to be true. This will allow Declude to be more efficient but will not log information about the other recipients in that email. This needs to be in the global.cfg.

COPYFILEACTIONWITHHEADERS    ON- This setting is married to the COPYFILE action and will ensure that header information is added to the mail message before the copy is performed. This the default process in Smartermail. This needs to be in the global.cfg.

ACTIONSONCOPYALL    ON - (IMAIL ONLY) Deleting email has changed since Declude version 1.82 allowing you to delete email on a per user level. A bug was found that actions were not applied on the copyall account. Defining ACTIONSONCOPYALL ON in global.cfg, will enable declude to apply actions on that account on a per user (user.junkmail) or global ($defautl$.junkmail) setting. This needs to be in the global.cfg.

NOACTIONSONCOPYALLWHENWHITELISTED - (IMAIL ONLY) If a email is whitelisted and had the copyall account added in the headers AND the ACTIONSONCOPYALL directive is defined, it will not take actions on the copyall account for the one email. This needs to be in the global.cfg.

WHITELIST   LOCAL
This directive causes all email between local domains (all domains hosted on the local server) to be whitelisted. The sender and *all* recipients must be local. A single remote recipient will cause the email not to be whitelisted.

Declude.cfg (Advanced Configuration)

20. Release Notes

You can view the Release Notes online

21. User License Agreement

You can view the EULA online