Mailets and Matchers Reference



Matches all mail.


Checks if at least one attachment has a file name which matches any element of a comma-separated or space-separated list of file name masks.

Syntax: match="AttachmentFileNameIs=[-d] [-z] masks"

The match is case insensitive.

File name masks may start with a wildcard '*'.

Multiple file name masks can be specified, e.g.: '*.scr,*.bat'.

If '-d' is coded, some debug info will be logged.

If '-z' is coded, the check will be non-recursively applied to the contents of any attached '*.zip' file.


Returns positive if the recipient is a command for a listserv. For example, if my listserv is, this matcher will return true for and


CommandListservMatcher is the matcher that pairs with the {@link org.apache.james.transport.mailets.CommandListservManager} It checks to see if the request is intended for the ListservManager, but doesn't guarantee that it is a valid command.
To configure, insert this into the config.xml inside of the root processor block.
<mailet match="CommandListservMatcher=announce@localhost" class="CommandListservManager">


Matches mails containing a header with a numeric value whose comparison with the specified value is true. If the header is missing in the message, there will be no match

Configuration string: The headerName, a comparison operator and the numeric headerValue to compare with, space or tab delimited.

The comparison operators are: <, <=, ==, >=, >; another set of operators is: LT, LE, EQ, GE, GT. Also the following operators are accepted: =<, =, =>.


<mailet match="CompareNumericHeaderValue=X-MessageIsSpamProbability > 0.9" class="ToProcessor">
<processor> spam </processor>


Matches mail with a header set by Fetchpop X-fetched-from
fetchpop sets X-fetched-by to the "name" of the fetchpop fetch task.
This is used to match all mail fetched from a specific pop account. Once the condition is met the header is stripped from the message to prevent looping if the mail is re-inserted into the spool. $Id: 713949 2008-11-14 07:40:21Z rdonkin $


Checks whether this message has an attachment


Matcher Info: Habeas Warrant Mark Matcher (see for details).

This matcher tests for the Hebeas Warrant Mark. For details see:

Usage: Place this matcher

<mailet match="HasHabeasWarrantMark" class="ToProcessor">
<processor> transport </processor>

in the root processs before the DNSRBL block lists (the InSpammerBlacklist matcher).

Because the Habeas Warrant Mark is copyright material, I have asked for and received the following explicit statement from Habeas:

From: Lindsey Pettit []
Sent: Sunday, September 29, 2002 5:51
To: Noel J. Bergman
Subject: RE: Habeas and Apache James

Dear Noel,

> I guess that since your Warrant Mark is copyright, I should ask for
> something from you to explicitly authorize that Hebeas will permit
> this code to be included and distributed as part of Apache James
> under the Apache Software License. As we have established, the use
> of the Habeas Warrant Mark for filtering is not restricted, but I
> would like something to confirm that, so that Apache will be happy.

I can hereby confirm to you that there is no license necessary in
order to use the Habeas mark for filtering. That said, however, we
do insist that it not ever be used as a basis for rejecting email which
bears the Habeas mark.


<mailet match="HasHeader={<header>[=value]}+" class="..." />

This matcher checks if the header named is present. If complements the AddHeader mailet.


Matcher Info: Has Mail Attribute Matcher

This Matcher determines if the mail contains the attribute specified in the condition, and returns all recipients if it is the case.

Sample configuration:

<mailet match="HasMailAttribute=whatever" class="<any-class>">


Matcher Info: Has Mail Attribute With Value Matcher

This Matcher determines if the mail contains the attribute specified in the condition and if the value answered when the method toString() is invoked on the attribute is equal to the String value specified in the condition. If both tests are true, all recipients are returned, else null.


The current matcher implementation expects a single String value to match on. This matcher requires two values, the attribute name and attribute value. This requires some implicit rules to govern how the single value supplied to the matcher is parsed into two values.

  • In the match condition, the split between the attribute name and the attribute value is made at the first comma. Attribute names that include a comma will parse incorrectly and therefore are not supported by this matcher.
  • Leading and trailing spaces are removed from both the attribute name and attribute value specified in the condition and the tested attribute value in the mail prior to matching. Therefore, "abc" , " abc", "abc " and " abc " are considered equivalent.
  • To test for an empty string, do not specify an attribute value after the comma.

Sample configuration:

<mailet match="HasMailAttributeWithValue=name, value" class="<any-class>">


Matches mail from given hosts.


Matches mail from localhost.


Matches mail where the number of recipiants is exactly one.


Matches mail where the recipent is one of a configurable list.


Matches mail where the recipient is local.


Matches mail which has been relayed more than a given number of times.


Matches mails that are sent by an SMTP authenticated user.

If the sender was not authenticated it will not match.

<mailet match="SMTPAuthSuccessful" class="<any-class>">


Matches mails that are sent by an SMTP authenticated user present in a supplied list.

If the sender was not authenticated it will not match.

Configuration string: a comma, tab or space separated list of James users.

<mailet match="SMTPAuthUserIs=<list-of-user-names>" class="<any-class>">


Matches mails that are sent by an client which is allowed to relay.

 <mailet match="SMTPIsAuthNetwork"


Checkes the sender's displayed domain name against a supplied list.

Sample configuration:

<mailet match="" class="ToProcessor">
<processor> spam </processor>


Checks the sender's displayed domain name against a the hosts serviced by this mail context.

Sample Configuration:

<mailet match="SenderHostIsLocal" class="SpamAssassin"> </mailet>


Matches mail where the sender is contained in a configurable list.


Matches mails that are sent by a null sender.

<mailet match="SenderIsNull" class="<any-class>">


Checks whether the message (entire message, not just content) is greater than a certain number of bytes. You can use 'k' and 'm' as optional postfixes. In other words, "1m" is the same as writing "1024k", which is the same as "1048576".


Matches mail where the subject is contained in a configurable list.


Matches mail where the subject starts with a given phrase.


Matches mail where the user is contained in a configurable list.



Mailet Info: AddFooter Mailet
This mailet will attach text to the end of the message (like a footer). Right now it only supports simple messages without multiple parts.


Mailet Info: Add Habeas Warrant Mark. Must be used in accordance with a license from Habeas (see for details).

This matcher adds the Hebeas Warrant Mark to a message. For details see:


<mailet match="<suitable-matcher>" class="AddHabeasWarrantMark" />

NOTE: Although this mailet is covered by the Apache Software License, the Habeas Warrant Mark is copyright. A separate license from Habeas is required in order to legally attach the Habeas Warrant Mark to e-mail messages. Each James Administrator is responsible for ensuring that James is configured to attach the Habeas Warrant Mark only to e-mail covered by a suitable license received from Habeas. Because the Habeas Warrant Mark is copyright material, I have asked for and received the following explicit statement from Habeas:

From: Lindsey Pettit []
Sent: Sunday, September 29, 2002 5:51
To: Noel J. Bergman
Subject: RE: Habeas and Apache James

Dear Noel,

> FURTHERMORE, if James is to be capable of sending Habeas SWE, I need
> to write a Mailet that attaches the headers. As with any MTA, it
> would be up to the administrator to properly configure James and make
> sure that licenses are acquired. Since the Habeas Warrant Mark is
> copyright, I believe that I require authorization from you for that
> Mailet, especially since it attaches the Habeas Warrant Mark. For my
> own protection, please show me why such authorization is unnecessary,
> send me a digitally signed e-mail, or FAX a signed authorization

You do not yourself need the authorization to build the functionality
into the [mailet]; what one needs authorization, in the form of a
license, for, is to use the mark *in headers*, in outgoing email.
However, please let me know if you would like something more
formal, and I can try to have something faxed to you.

> The Mailet docs would reference the Habeas website, and inform
> administrators that in order to USE the mailet, they need to ensure
> that they have whatever licenses are required from you as appropriate
> to your licensing terms.

That's absolutely perfect!


Mailet Info: AddSubjectPrefix Mailet
Add an prefix (tag) to the subject of a message

Sample Configuration:

<mailet match="" class="TagMessage">
<subjectPrefix>[robot]</subjectPrefix> </mailet> 


Mailet Info: Antivirus Check using ClamAV (CLAMD)

Does an antivirus scan check using a ClamAV daemon (CLAMD)

Interacts directly with the daemon using the "stream" method, which should have the lowest possible overhead.

The CLAMD daemon will typically reside on localhost, but could reside on a different host. It may also consist on a set of multiple daemons, each residing on a different server and on different IP number. In such case a DNS host name with multiple IP addresses (round-robin load sharing) is supported by the mailet (but on the same port number).

Handles the following init parameters:

  • <debug>.
  • <host>: the host name of the server where CLAMD runs. It can either be a machine name, such as "", or a textual representation of its IP address. If a literal IP address is supplied, only the validity of the address format is checked. If the machine name resolves to multiple IP addresses, round-robin load sharing will be used. The default is localhost.
  • <port>: the port on which CLAMD listens. The default is 3310.
  • <maxPings>: the maximum number of connection retries during startup. If the value is 0 no startup test will be done. The default is 6.
  • <pingIntervalMilli>: the interval (in milliseconds) between each connection retry during startup. The default is 30000 (30 seconds).
  • <streamBufferSize>: the BufferedOutputStream buffer size to use writing to the stream connection. The default is 8192.

The actions performed are as follows:

  • During initialization:
    1. Gets all config.xml parameters, handling the defaults;
    2. resolves the <host> parameter, creating the round-robin IP list;
    3. connects to CLAMD at the first IP in the round-robin list, on the specified <port>;
    4. if unsuccessful, retries every <pingIntervalMilli> milliseconds up to <maxPings> times;
    5. sends a PING request;
    6. waits for a PONG answer;
    7. repeats steps 3-6 for every other IP resolved.
  • For every mail
    1. connects to CLAMD at the "next" IP in the round-robin list, on the specified <port>, and increments the "next" index; if the connection request is not accepted tries with the next one in the list unless all of them have failed;
    2. sends a "STREAM" request;
    3. parses the "PORT streamPort" answer obtaining the port number;
    4. makes a second connection (the stream connection) to CLAMD at the same host (or IP) on the streamPort just obtained;
    5. sends the mime message to CLAMD (using {@link MimeMessage#writeTo(}) through the stream connection;
    6. closes the stream connection;
    7. gets the "OK" or "... FOUND" answer from the main connection;
    8. closes the main connection;
    9. sets the "org.apache.james.infected" mail attribute to either "true" or "false";
    10. adds the "X-MessageIsInfected" header to either "true" or "false";

Some notes regarding clamav.conf:

  • LocalSocket must be commented out
  • TCPSocket must be set to a port# (typically 3310)
  • StreamMaxLength must be >= the James config.xml parameter <maxmessagesize> in SMTP <handler>
  • MaxThreads should? be >= the James config.xml parameter <threads> in <spoolmanager>
  • ScanMail must be uncommented

Here follows an example of config.xml definitions deploying CLAMD on localhost, and handling the infected messages:


<!-- Do an antivirus scan -->
<mailet match="All" class="ClamAVScan" onMailetException="ignore"/>

<!-- If infected go to virus processor -->
<mailet match="HasMailAttributeWithValue=org.apache.james.infected, true" class="ToProcessor">
<processor> virus </processor>

<!-- Check attachment extensions for possible viruses -->
<mailet match="AttachmentFileNameIs=-d -z *.exe *.com *.bat *.cmd *.pif *.scr *.vbs *.avi *.mp3 *.mpeg *.shs" class="ToProcessor">
<processor> bad-extensions </processor>


<!-- Messages containing viruses -->
<processor name="virus">

<!-- To avoid a loop while bouncing -->
<mailet match="All" class="SetMailAttribute">
<org.apache.james.infected>true, bouncing</org.apache.james.infected>

<mailet match="SMTPAuthSuccessful" class="Bounce">
<notice> Warning: We were unable to deliver the message below because it was found infected by virus(es). </notice>

<mailet match="All" class="ToRepository">

<mailet match="All" class="Null" />


Mailet Info: Counter Mailet
A simple in memory counter. Designed to count messages sent to this recipient for debugging purposes.


Mailet Info: Dumps message to System.err
Debugging purpose Mailet. Sends the message to System.err


Mailet Info: ExceptionThrowingMailet Mailet
Debugging purpose Mailet. Just throws an exception.


Mailet Info: Identity Mailet
Opposite of Null Mailet. It let any incoming mail untouched. Used only for debugging.


Mailet Info: LogHeaders Mailet
Logs Message Headers and/or Body. If the "passThrough" in confs is true the mail will be left untouched in the pipe. If false will be destroyed. Default is true.


Convert attributes to headers

Sample configuration:

<mailet match="All" class="MailAttributesToMimeHeaders">
headerName2</simplemapping> </mailet>


Mailet Info: Null Mailet
Simplest Mailet which destroys any incoming messages.


Mailet Info: OnlyText
Keep only the text part of a message.

If the message is text only then it doesn't touch it, if it is a multipart it transform it a in plain text message with the first text part found.
- text/plain
- text/html => with a conversion to text only
- text/* as is.


Mailet Info: Postmaster aliasing mailet

Rewrites recipient addresses to make sure email for the postmaster is always handled. This mailet is silently inserted at the top of the root spool processor. All recipients mapped to postmaster@ are changed to the postmaster account as specified in the server conf.


Mailet Info: RecoverAttachment Mailet

This mailet takes an attachment stored in an attribute and attach it back to the message

This may be used to place back attachment stripped by StripAttachment and stored in the attribute org.apache.james.transport.mailets.StripAttachment.saved

<mailet match="All" class="RecoverAttachment" >
</mailet >


Mailet Info: Remove All Mail Attributes Mailet

This mailet sets removes all attributes set on the Mail instance Sample configuration:

<mailet match="All" class="RemoveAllMailAttributes"/>


Mailet Info: Remove Mail Attribute Mailet

This mailet sets attributes on the Mail. Sample configuration:

<mailet match="All" class="RemoveMailAttribute">


Mailet Info: RemoveMimeHeader Mailet

Remove mime headers Sample configuration:

<mailet match="All" class="RemoveMimeHeader">


Mailet Info: ReplaceContent

Replace text contents

This mailet allow to specific regular expression to replace text in subject and content.


REGEX_PATTERN is a regex used for the match
SUBSTITUTION_PATTERN is a substitution pattern
FLAGS flags supported for the pattern:
i: case insensitive
m: multi line
x: extended (N/A)
r: repeat - keep matching until a substitution is possible

To identify subject and body pattern we use the tags <subjectPattern> and <bodyPattern>

Rules can be specified in external files. Lines must be CRLF terminated and lines starting with # are considered commments. Tags used to include external files are <subjectPatternFile> and <bodyPatternFile> If file path starts with # then the file is loaded as a reasource.

Use of both files and direct patterns at the same time is allowed.

This mailet allow also to enforce the resulting charset for messages processed. To do that the tag <charset> must be specified.

NOTE: Regexp rules must be escaped by regexp excaping rules and applying this 2 additional rules:
- "/" char inside an expression must be prefixed with "\": e.g: "/\//-//" replaces "/" with "-"
- when the rules are specified using <subjectPattern> or <bodyPattern> and "/,/" has to be used in a pattern string it must be prefixed with a "\". E.g: "/\/\/,//" replaces "/" with "," (the rule would be "/\//,//" but the "/,/" must be escaped.


Mailet Info: ServerTime Mailet

Returns the current time for the mail server. Sample configuration:

<mailet match="" class="ServerTime">


Mailet Info: Set Mail Attribute Mailet

This mailet sets attributes on the Mail.

Sample configuration:

<mailet match="All" class="SetMailAttribute">


Mailet Info: SetMimeHeader Mailet

Adds a specified header and value to the message.

Sample configuration:

<mailet match="All" class="AddHeader">


Mailet Info: StripAttachment

Remove attachments from a Message. Supports simple removal, storing to file, or storing to mail attributes.


<mailet match="All" class="StripAttachment" >
<pattern >.*\.xls </pattern> <!-- The regular expression that must be matched -- >
<!-- notpattern >.*\.xls </notpattern--> <!-- The regular expression that must be matched -- >
<directory >c:\temp\james_attach </directory> <!-- The directory to save to -- >
<remove >all </remove> <!-- either "no", "matched", "all" -- >
<!-- attribute></attribute -->
</mailet >


Mailet Info: ToProcessor Mailet

This mailet redirects the mail to the named processor

Sample configuration:

<mailet match="All" class="ToProcessor">
<notice>Notice attached to the message (optional)</notice>


Mailet Info: UnwrapText

Remove (best effort to) the hardcoded wrapping from a message.
If the text is "format=flowed" then deflows the text. Otherwise it forces a dewrap of the text.

quotewidth - when we try to dewrap e quoted text it helps knowing the original with, so we can reconstruct "wrapped wraps" created by multiple wrappings by clients with different original width or simply to the add of the heading ">" that increase the line length.
The value should be "WIDTH+X" if the original length is known, "-X" otherwise. In the latter case the length of the longer line will be used. X is the tollerance needed for the quoting chars: if the original width is known the suggested value for X is 2 (because of "> " prefix), otherwise it is suggested to increase it to a value like 10 (-10)

In summary, if the original wrap is known (for example 76, for flowed messages)
quotewidth = 78
quotewidth = -10


Mailet Info: UseHeaderRecipients Mailet

Mailet designed to process the recipients from the mail headers rather than the recipients specified in the SMTP message header. This can be useful if your mail is redirected on-route by a mail server that substitutes a fixed recipient address for the original.

To use this, match against the redirection address using the RecipientIs matcher and set the mailet 'class' to UseHeaderRecipients. This will cause the email to be re-injected into the root process with the recipient substituted by all the recipients in the Mail-For, To and Cc headers of the message.


<mailet match="RecipientIs=forwarded@myhost"


Mailet Info: WrapText

Convert a message to format=flowed