The Apache Software Foundation

Deleted Messages Vault

This document will help you understand what is Deleted Messages Vault. And finally, present to you, how to setup James Server with this feature.

  • What is Deleted Messages Vault
  • How to setup James with Deleted Messages Vault
  • How to administrate Deleted Messages Vault

What is Deleted Messages Vault

Deleted Messages Vault is a feature in James, it allows you to:

  • retain user deleted messages for some time
  • restore & export deleted messages by various criteria
  • permanently delete some retained messages

If Deleted Messages Vault is enabled, when users delete their mails, James will retain these mails into Deleted Messages Vault. And only administrators can interact with this component via WebAdmin REST APIs.

One useful use of that feature is to allow an administrator to restore some mails an user may have deleted by accident. However, mails are not retained forever as you have to configure a retention period before using it (we'll see later how to trigger the collection of mails). It's also possible to permanently delete a mail if needed.

Deleted mails for exporting & restoring can be filtered via several criteria based on mail properties. At the moment, these are supported mail properties for filtering:

  • deletion date(ISO-8601 Date String)
    • supports before or equals operator
    • supports after or equals operator
  • delivery date(ISO-8601 Date String)
    • supports before or equals operator
    • supports after or equals operator
  • recipients(List of string)
    • supports contains operator
  • sender(String)
    • supports equal matching operator
  • has attachment(Boolean)
    • supports equal matching operator
  • subject(String)
    • supports equal matching operator
    • supports equal ignore case matching operator
    • supports contains matching operator
    • supports contains ignore case matching operator (with US locale)

How to setup James with Deleted Messages Vault

In this section, we will guide you to setup James with Deleted Message Vault by following below steps:

  • Enable Deleted Messages Vault
  • Make James uses Deleted Messages Vault by configuring Pre Deletion Hooks
  • Starting James with enabled Deleted Message Vault by docker compose

Enable Deleted Messages Vault

To do this, you have to create a configuration file deletedMessageVault.properties, then put it into conf directory of James. There are two available properties you may want to configure:

  • urlPrefix: represent for the prefix of namespace Deleted Messages Vault will use to store deleted messages.
  • retentionPeriod: represent for the period deleted messages allowed to be stored in Deleted Messages Vault.

Example:


urlPrefix=cassandra://var/deletedMessages/vault
retentionPeriod=1 year
                

More details about configuration & example is at Deleted Messages Vault Configuration

Make James uses Deleted Messages Vault by configuring Pre Deletion Hooks

By default, although Deleted Messages Vault has been configured, but, to make it really work, you still need to configure Pre Deletion Hooks to lets James use it. Before deleting a mail in James, PreDeletionHooks will be triggered to execute all hooks. If all hook executions success, then James will process to delete that mail. There is already a DeletedMessageVaultHook in James, its job to store deleted mails into Deleted Messages Vault. Thus, you need to configure this hook in listeners.xml configuration file.

Sample DeletedMessageVaultHook configuration:


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

More details about configuration & example is at Pre Deletion Hook Configuration

Starting James with enabled Deleted Message Vault by docker compose

We will take James cassandra product for the example

First, get template cassandra product configuration:


$ git clone https://github.com/apache/james-project
$ cp -rf james-project/dockerfiles/run/guice/cassandra/destination/conf conf
                

Then create the keystore file in the conf/ directory with the default password james72laBalle


$ keytool -genkey -alias james -keyalg RSA -keystore conf/keystore
                

Second, modify deletedMessageVault.properties configuration file like an example at previous paragraph

Third, modify listeners.xml to configure DeletedMessageVaultHook by adding preDeletionHook section at previous paragraph

Fourth, We will create a local folder for holding data out of the container:


mkdir var
                

Finally, starting a James Server by docker compose

Getting James docker-compose.yml


$ wget https://raw.githubusercontent.com/apache/james-project/master/dockerfiles/run/docker-compose.yml
                

Add the following volumes for james service:


volumes:
  - $PWD/conf:/root/conf/
  - $PWD/var:/root/var/
                

How to administrate Deleted Messages Vault

These are supported WebAdmin features on top of Deleted Messages Vault. You can have a look at WebAdmin Deleted Messages Vault document at here

WebAdmin Deleted Messages Vault exporting

This part is a bit special to you, you are able to choose which exporting mechanism to be used. At the moment there are one available exporting mechanism

  • localFile: This is a simple exporting mechanism while with an export request, it retrieves deleted mails from Deleted Messages Vault, then store them as a zip file in local file system in James Server. Then sending a mail with the absolute path of exported file to the targeted mail address.

You can configure which kind of export mechanism to use in James by specifying blob.export.implementation in blobStore.properties configuration file. E.g:


blob.export.implementation=localFile
                

More details about configuration & example at Blob Export Configuration