Mailets and Matchers Reference

Items marked as Experimental are not yet supported by James; however, you can try them.


AbstractQuotaMatcher (Experimental)

Abstract matcher checking whether a recipient has exceeded a maximum allowed quota.

"Quota" at this level is an abstraction whose specific interpretation will be done by subclasses.

Although extending GenericMatcher, its logic is recipient oriented.


Matches all mail.

AttachmentFileNameIs (Experimental)

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.

CommandForListserv (Experimental)

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 (Experimental)

CommandListservMatcher is the matcher that pairs with the 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">

CompareNumericHeaderValue (Experimental)

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$

FileRegexMatcher (Experimental)

Initializes RegexMatcher with regular expressions from a file.


This is a generic matcher that uses regular expressions. If any of the regular expressions match, the matcher is considered to have matched. This is an abstract class that must be subclassed to feed patterns. Patterns are provided by calling the compile method. A subclass will generally call compile() once during init(), but it could subclass match(), and call it as necessary during message processing (e.g., if a file of expressions changed).


Checks whether this message has an attachment

HasHabeasWarrantMark (Experimental)

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>">


Matcher Info: Has Mail Attribute Value Matcher

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

Sample configuration:

<mailet match="HasMailAttributeWithValueRegex=whatever," class="<any-class>">
Note: as it is not possible to put arbitrary objects in the configuration, toString() is called on the attribute value, and that is the value matched against.


Matches mail to given hosts.


Matches mail to Domains which are local .


Matches mail where the number of recipiants is exactly one.

NESSpamCheck (Experimental)

This is based on a sample filter.cfg for a Netscape Mail Server to stop spam.


This matcher matches a specific recipient (in the envelope of the mail), passed as a condition to this matcher.

The example below will match only the recipient user@domain

<mailet match="RecipientIs=user@domain" class="<any-class>">


Matches mail where the recipient is local.


Matches recipients whose address matches a regular expression.

Is equivalent to the {@link SenderIsRegex} matcher but matching on the recipient.

Configuration string: a regular expression.

<mailet match="RecipientIsRegex=<regular-expression>" class="<any-class>">

The example below will match any recipient in the format user@log.anything

<mailet match="RecipientIsRegex=(.*)@log\.(.*)" class="<any-class>">


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>">

SMTPIsAuthNetwork (Experimental)

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>


This matcher matches a specific sender, passed as a condition to this matcher.

The example below will match mail with a sender being user@domain

<mailet match="SenderIs=user@domain" class="<any-class>">


Matches mail where the sender is local.


Matches mails that are sent by a null sender.

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


Matches mails that are sent by a sender whose address matches a regular expression.

Is equivalent to the {@link RecipientIsRegex} matcher but matching on the sender.

Configuration string: a regular expression.

<mailet match="SenderIsRegex=<regular-expression>" class="<any-class>">

The example below will match any sender in the format user@log.anything

<mailet match="SenderIsRegex=(.*)@log\.(.*)" class="<any-class>">

Another example below will match any sender having some variations of the string mp3 inside the username part.

<mailet match="SenderIsRegex=(.*)(mp3|emmepitre)(.*)@" class="<any-class>">


This matcher matches email sent automatically by mailets.

<mailet match="SentByMailetAny" class="<any-class>"/>
This matcher allows you, for instance, to enable/disable routing automatically generated emails out of your server.


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.


This matcher matches emails that have too many lines. This allows better rejection of emails when, for instance, MIME4J is configured with a limited number of lines.

The example below will match mail with more than 10000 lines

<mailet match="TooManyLines=10000" class="<any-class>"/>


This matcher matches emails that have too many recipients.

The example below will reject any email with more than 5 recipients

<mailet match="TooManyRecipients=5" class="<any-class>"/>


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



This mailet adds the de-facto standard QMail Delivered-To header. Upon processing by LocalDelivery, a Delivered-To header matching the recipient mail address will be added before storage.

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


Mailet Info: AddFooter Mailet

Takes the message and attaches a footer message to it. Right now, it only supports simple messages. Needs to have additions to make it support messages with alternate content types or with attachments.

AddHabeasWarrantMark (Experimental)

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: AmqpForwardAttribute

This mailet forwards the attributes values to a AMPQ.
It takes 4 parameters:

  • attribute (mandatory): content to be forwarded, expected to be a Map<String, byte[]> where the byte[] content is issued from a MimeBodyPart. It is typically generated from the StripAttachment mailet.
  • uri (mandatory): AMQP URI defining the server where to send the attachment.
  • exchange (mandatory): name of the AMQP exchange.
  • routing_key (optional, default to empty string): name of the routing key on this exchange.
This mailet will extract the attachment content from the MimeBodyPart byte[] before sending it.

ClamAVScan (Experimental)

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> </mailet>

<!-- 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> </mailet>


<!-- 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>

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

<!-- <mailet match="All" class="ToRepository"> <repositoryPath>file://var/mail/infected/</repositoryPath> </mailet> -->

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

ClassifyBounce (Experimental)

Mailet Info: SetMimeHeader Mailet

Assesses the message to determine if it was a hard or soft bounce, and if it was a soft bounce, something of its nature..

Sample configuration:



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.

HeadersToHTTP (Experimental)

Mailet Info: HTTP POST serialised message

Serialise the email and pass it to an HTTP call Sample configuration: Test ParameterValue true


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: MimeDecodingMailet

This mailet replace the mail attribute map of key to MimePart by a map of key to the MimePart content (as bytes).
It takes only one parameter:

  • attribute (mandatory): mime content to be decoded, expected to be a Map<String, byte[]>
Then all this map attribute values will be replaced by their content.


Mailet Info: Null Mailet

Simplest Mailet which destroys any incoming messages by setting their state to GHOST

OnlyText (Experimental)

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.


{@link GenericMailet} which convert all Recipients to lowercase

RecoverAttachment (Experimental)

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.mailet.standard.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, when a replacement has been done. 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.

SerialiseToHTTP (Experimental)

Mailet Info: HTTP POST serialised message

Serialise the email and pass it to an HTTP call Sample configuration: URL url where serialised message will be posted ParameterKey An arbitrary parameter be added to the post ParameterValue A value for the arbitrary parameter MessageKeyName Field name for the serialised message passThrough true or false

ServerTime (Experimental)

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 -- >
    <mimeType>text/calendar</mimeType>  <!-- The matching mimeType -- >
    <directory >c:\temp\james_attach </directory>   <!-- The directory to save to -- >
    <remove >all </remove>   <!-- either "no", "matched", "all" -- >
    <!-- attribute></attribute -->
  </mailet >
  At least one of pattern, notpattern and mimeType is required.


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>

UnwrapText (Experimental)

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

UseHeaderRecipients (Experimental)

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"

WrapText (Experimental)

Mailet Info: WrapText

Convert a message to format=flowed