docs/modules/servers/pages/distributed/configure/smtp-hooks.adoc

= Distributed James Server — SMTP Hooks
:navtitle: SMTP Hooks

This documentation page lists and documents SMTP hooks that can be used within the
Distributed Server SMTP protocol stack in order to customize the way your SMTP server
behaves without of the box components.

== DNSRBLHandler

This command handler check against https://www.wikiwand.com/en/Domain_Name_System-based_Blackhole_List[RBL-Lists]
(Real-time Blackhole List).

If getDetail is set to true it try to retrieve information from TXT Record
why the ip was blocked. Default to false.

before you enable out the DNS RBL handler documented as an example below,
please take a moment to review each block in the list.
We have included some that various JAMES committers use,
but you must decide which, if any, are appropriate
for your environment.

The mail servers hosting
@apache.org mailing lists, for example, use a
slightly different list than we have included below.
And it is likely that most JAMES committers also have
slightly different sets of lists.

The SpamAssassin user's list would be one good place to discuss the
measured quality of various block lists.

NOTA BENE: the domain names, below, are terminated
with '.' to ensure that they are absolute names in
DNS lookups.  Under some circumstances, names that
are not explicitly absolute could be treated as
relative names, leading to incorrect results.  This
has been observed on *nix and MS-Windows platforms
by users of multiple mail servers, and is not JAMES
specific.  If you are unsure what this means for you,
please speak with your local system/network admins.

This handler should be considered experimental.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.fastfail.DNSRBLHandler">
        <getDetail>false</getDetail>
        <rblservers>
            <whitelist>query.bondedsender.org.</whitelist>
            <blacklist>sbl-xbl.spamhaus.org.</blacklist>
            <blacklist>dul.dnsbl.sorbs.net.</blacklist>
            <blacklist>list.dsbl.org.</blacklist>
        </rblservers>
    </handler>
</handlerchain>
....

== DSN hooks

The Distributed server has optional support for DSN (link:https://tools.ietf.org/html/rfc3461[RFC-3461])

Please read carefully xref:distributed/configure/dsn.adoc[this page].

....
<smtpserver enabled="true">
    <...> <!-- The rest of your SMTP configuration, unchanged -->
    <handlerchain>
        <handler class="org.apache.james.smtpserver.dsn.DSNEhloHook"/>
        <handler class="org.apache.james.smtpserver.dsn.DSNMailParameterHook"/>
        <handler class="org.apache.james.smtpserver.dsn.DSNRcptParameterHook"/>
        <handler class="org.apache.james.smtpserver.dsn.DSNMessageHook"/>
        <...> <!-- other handlers, like: -->
        <handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/> <!-- for instance -->
    </handlerchain>
</smtpserver>
....

Note that a specific configuration of xref:distributed/configure/mailetcontainer.adoc[mailetcontainer.xml] is
required as well to be spec compliant.

== MailPriorityHandler

This handler can add a hint to the mail which tells the MailQueue which email should get processed first.

Normally the MailQueue will just handle Mails in FIFO manner.

Valid priority values are 1,5,9 where 9 is the highest.

This handler should be considered experimental.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.MailPriorityHandler">
        <priorityEntries>
            <priorityEntry>
               <domain>yourdomain1</domain>
               <priority>1</priority>
            </priorityEntry>
            <priorityEntry>
               <domain>yourdomain2</domain>
               <priority>9</priority>
            </priorityEntry>
        <priorityEntries>
    </handler>
</handlerchain>
....

== MaxRcptHandler
If activated you can limit the maximal recipients.

This handler should be considered experimental.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.fastfail.MaxRcptHandler">
        <maxRcpt>10</maxRcpt>
    </handler>
</handlerchain>
....

== POP3BeforeSMTPHandler

This connect handler can be used to enable POP3 before SMTP support.

Please note that only the ip get stored to identify an authenticated client.

The expireTime is the time after which an ipAddress is handled as expired.

This handler should be considered as unsupported.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.POP3BeforeSMTPHandler">
        <expireTime>1 hour</expireTime>
    </handler>
</handlerchain>
....

== ResolvableEhloHeloHandler

Checks for resolvable HELO/EHLO before accept the HELO/EHLO.

If checkAuthNetworks is set to true sender domain will be checked also for clients that
are allowed to relay. Default is false.

This handler should be considered experimental.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.fastfail.ResolvableEhloHeloHandler"/>
</handlerchain>
....

== ReverseEqualsEhloHeloHandler

Checks HELO/EHLO is equal the reverse of the connecting client before accept it
If checkAuthNetworks is set to true sender domain will be checked also for clients that
are allowed to relay. Default is false.

This handler should be considered experimental.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.fastfail.ReverseEqualsEhloHeloHandler"/>
</handlerchain>
....

== SetMimeHeaderHandler

This handler allows you to add mime headers to the processed mails.

This handler should be considered experimental.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.SetMimeHeaderHandler">
        <headername>SPF-test</headername>
        <headervalue>passed</headervalue>
    </handler>
</handlerchain>
....

== SpamAssassinHandler

This MessageHandler could be used to check message against spamd before
accept the email. So it's possible to reject a message on smtplevel if a
configured hits amount is reached.

This handler should be considered experimental.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.fastfail.SpamAssassinHandler">
        <spamdHost>127.0.0.1</spamdHost>
        <spamdPort>783</spamdPort>
        <spamdRejectionHits>10</spamdRejectionHits>
    </handler>
</handlerchain>
....

== SPFHandler

This command handler can be used to reject emails with not match the SPF record of the sender domain.

If checkAuthNetworks is set to true sender domain will be checked also for clients that
are allowed to relay. Default is false.

This handler should be considered experimental.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.fastfail.SPFHandler">
        <blockSoftFail>false</blockSoftFail>
        <blockPermError>true</blockPermError>
    </handler>
</handlerchain>
....

== URIRBLHandler

This MessageHandler could be used to extract domain out of the message and check
this domains against uriRbllists. See http://www.surbl.org for more information.
The message get rejected if a domain matched.

This handler should be considered experimental.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.fastfail.URIRBLHandler">
        <action>reject</action>
        <getDetail>true</getDetail>
        <uriRblServers>
            <server>multi.surbl.org</server>
        </uriRblServers>
    </handler>
</handlerchain>
....

== ValidRcptHandler

With ValidRcptHandler, all email will get rejected which has no valid user.

You need to add the recipient to the validRecipient list if you want
to accept email for a recipient which not exist on the server.

If you want James to act as a spamtrap or honeypot, you may comment ValidRcptHandler
and implement the needed processors in spoolmanager.xml.

This handler should be considered stable.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.fastfail.ValidRcptHandler"/>
</handlerchain>
....

== ValidSenderDomainHandler

If activated mail is only accepted if the sender contains
a resolvable domain having a valid MX Record or A Record associated!

If checkAuthNetworks is set to true sender domain will be checked also for clients that
are allowed to relay. Default is false.

Example configuration:

....
<handlerchain>
    <!-- ... -->
    <handler class="org.apache.james.smtpserver.fastfail.ValidSenderDomainHandler"/>
</handlerchain>
....

== FUTURERELEASE hooks

The Distributed server has optional support for FUTURERELEASE (link:https://www.rfc-editor.org/rfc/rfc4865.html[RFC-4865])

....
<smtpserver enabled="true">
    <...> <!-- The rest of your SMTP configuration, unchanged -->
    <handlerchain>
        <handler class="org.apache.james.smtpserver.futurerelease.FutureReleaseEHLOHook"/>
        <handler class="org.apache.james.smtpserver.futurerelease.FutureReleaseMailParameterHook"/>
        <handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/>
    </handlerchain>
</smtpserver>
....

== Message Transfer Priorities hooks

The Distributed server has optional support for SMTP Extension for Message Transfer Priorities (link:https://www.rfc-editor.org/rfc/rfc6710.html[RFC-6710])

The SMTP server does not allow positive priorities from unauthorized sources and sets the priority to the default value (0).

....
<smtpserver enabled="true">
    <...> <!-- The rest of your SMTP configuration, unchanged -->
    <handlerchain>
        <handler class="org.apache.james.smtpserver.priority.SmtpMtPriorityEhloHook"/>
        <handler class="org.apache.james.smtpserver.priority.SmtpMtPriorityParameterHook"/>
        <handler class="org.apache.james.smtpserver.priority.SmtpMtPriorityMessageHook"/>
        <handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/>
    </handlerchain>
</smtpserver>
....

== DKIM checks hooks

Hook for verifying DKIM signatures of incoming mails.

This hook can be restricted to specific sender domains and authenticate those emails against
their DKIM signature. Given a signed outgoing traffic this hook can use operators to accept legitimate
emails emitted by their infrastructure but redirected without envelope changes to there own domains by
some intermediate third parties. See link:https://issues.apache.org/jira/browse/JAMES-4032[JAMES-4032].

Supported configuration elements:

- *forceCRLF*: Should CRLF be forced when computing body hashes.
- *onlyForSenderDomain*: If specified, the DKIM checks are applied just for the emails whose MAIL FROM specifies this domain. If unspecified, all emails are checked (default).
- *signatureRequired*: If DKIM signature is checked, the absence of signature will generate failure. Defaults to false.
- *expectedDToken*: If DKIM signature is checked, the body should contain at least one DKIM signature with this d token. If unspecified, all d tokens are considered valid (default).

Example handlerchain configuration for `smtpserver.xml`:

....
<handlerchain>
    <handler class="org.apache.james.smtpserver.DKIMHook">
        <forceCLRF>true</forceCLRF>
        <onlyForSenderDomain>apache.org</onlyForSenderDomain>
        <signatureRequired>true</signatureRequired>
        <expectedDToken>apache.org</expectedDToken>
    </handler>
<handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/>
</handlerchain>
....

Would allow emails using `apache.org` as a MAIL FROM domain if, and only if they contain a
valid DKIM signature for the `apache.org` domain.