docs/modules/servers/pages/distributed/configure/listeners.adoc

= Distributed James Server — listeners.xml
:navtitle: listeners.xml

Distributed James relies on an event bus system to enrich mailbox capabilities. Each
operation performed on the mailbox will trigger related events, that can
be processed asynchronously by potentially any James node on a
distributed system.

Mailbox listeners can register themselves on this event bus system to be
called when an event is fired, allowing to do different kind of extra
operations on the system.

Distributed James allows the user to register potentially user defined additional mailbox listeners.

Consult this link:https://github.com/apache/james-project/blob/master/dockerfiles/run/guice/cassandra-rabbitmq/destination/conf/listener.xml[example]
to get some examples and hints.

== Configuration

The <executeGroupListeners> controls whether to launch group mailbox listener consumption. Defaults to true. Use with caution:
never disable on standalone james servers, and ensure at least some instances do consume group mailbox listeners within a
clustered topology.

Mailbox listener configuration is under the XML element <listener>.

Some MailboxListener allows you to specify if you want to run them synchronously or asynchronously. To do so,
for MailboxListener that supports this, you can use the *async* attribute (optional, per mailet default) to govern the execution mode.
If *true* the execution will be scheduled in a reactor elastic scheduler. If *false*, the execution is synchronous.

Already provided additional listeners are documented below.

=== SpamAssassinListener

Provides per user real-time HAM/SPAM feedback to a SpamAssassin server depending on user actions.

This mailet is asynchronous by default, but this behaviour can be overridden by the *async*
configuration property.

This MailboxListener is supported.

Example:

....
<listeners>
  <!-- ... -->
  <listener>
    <class>org.apache.james.mailbox.spamassassin.SpamAssassinListener</class>
  </listener>
</listeners>
....

Please note that a `spamassassin.properties` file is needed. Read also
xref:distributed/configure/spam.adoc[this page] for extra configuration required to support this feature.

=== MailboxOperationLoggingListener

Provides more insights on mailbox operationsby logging them.

This MailboxListener is supported.

Example:

....
<listeners>
  <listener>
    <class>org.apache.james.mailbox.cassandra.MailboxOperationLoggingListener</class>
  </listener>
  <!-- ... -->
</listeners>
....

=== QuotaThresholdCrossingListener

Sends emails to users exceeding 80% and 99% of their quota to warn them (for instance).

Here are the following properties you can configure:

.QuotaThresholdCrossingListener configuration properties
|===
| Property name | explanation

| name
| Useful when configuring several time this listener. You might want to do so to use different rendering templates for
different occupation thresholds.

| gracePeriod
| Period during which no more email for a given threshold should be sent.

| subjectTemplate
| Mustache template for rendering the subject of the warning email.

| bodyTemplate
| Mustache template for rendering the body of the warning email.

| thresholds
| Floating number between 0 and 1 representing the threshold of quota occupation from which a mail should be sent.
Configuring several thresholds is supported.

|===

Example:

....
<listeners>
  <!-- ... -->
  <listener>
    <class>org.apache.james.mailbox.quota.mailing.listeners.QuotaThresholdCrossingListener</class>
    <group>QuotaThresholdCrossingListener-upper-threshold</group>
    <configuration>
      <thresholds>
        <threshold>
          <value>0.8</value>
        </threshold>
      </thresholds>
      <name>thirst</name>
      <subjectTemplate>conf://templates/QuotaThresholdMailSubject.mustache</subjectTemplate>
      <bodyTemplate>conf://templates/QuotaThresholdMailBody.mustache</bodyTemplate>
      <gracePeriod>1week/</gracePeriod>
    </configuration>
  </listener>
</listeners>
....

Here are examples of templates you can use:

* For subject template: `conf://templates/QuotaThresholdMailSubject.mustache`

....
Warning: Your email usage just exceeded a configured threshold
....

* For body template: `conf://templates/QuotaThresholdMailBody.mustache`

....
You receive this email because you recently exceeded a threshold related to the quotas of your email account.

{{#hasExceededSizeThreshold}}
You currently occupy more than {{sizeThreshold}} % of the total size allocated to you.
You currently occupy {{usedSize}}{{#hasSizeLimit}} on a total of {{limitSize}} allocated to you{{/hasSizeLimit}}.

{{/hasExceededSizeThreshold}}
{{#hasExceededCountThreshold}}
You currently occupy more than {{countThreshold}} % of the total message count allocated to you.
You currently have {{usedCount}} messages{{#hasCountLimit}} on a total of {{limitCount}} allowed for you{{/hasCountLimit}}.

{{/hasExceededCountThreshold}}
You need to be aware that actions leading to exceeded quotas will be denied. This will result in a degraded service.
To mitigate this issue you might reach your administrator in order to increase your configured quota. You might also delete some non important emails.
....

This MailboxListener is supported.

== PreDeletionHook configuration

Before deleting a message in James, this message and some related information about the deletion will be passed to a set of PreDeletionHook instances,
This process is called notifying, and it acts sequentially. If the notifying process for all PreDeletionHooks finish successfully, then the message will be processed to be deleted.
Otherwise, that message won't be deleted.

Pre Deletion Hook configuration is under the XML element <preDeletionHook>

Already provided additional pre deletion hooks includes:

* `org.apache.james.vault.DeletedMessageVaultHook`: Storing messages about being deleted into
`org.apache.james.vault.DeletedMessageVault`


Example:

....
<listeners>
  <!-- ... -->
  <preDeletionHook>
    <class>org.apache.james.vault.DeletedMessageVaultHook</class>
  </preDeletionHook>
</listeners>
....

Read also xref:distributed/configure/vault.adoc[this page] for extra configuration required to support this feature.