The Apache Software Foundation

Deleted Messages Vault

The goal of this document is to help you to understand better about this feature and to present you the following topics:

  • What is Deleted Messages Vault ?
  • How to setup James with Deleted Messages Vault
  • Deleted Messages Vault administration
  • Example: Starting James with enabled Deleted Messages Vault by docker compose

What is Deleted Messages Vault ?

Deleted Messages Vault is a feature in James allowing you to:

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

If the Deleted Messages Vault is enabled, when users delete their mails, and by that we mean when he tries to definitely delete them by emptying the trash, James will retain these mails into the 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 (with a one year retention by default if not defined). 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 strings)
    • supports contains operator
  • sender (String)
    • supports equal matching operator
  • has attachment (Boolean)
    • supports equal matching operator
  • origin mailboxes (List of strings)
    • supports contains 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 Messages Vault by following the steps below:

  • Enable Deleted Messages Vault by configuring Pre Deletion Hooks
  • Configuring your BlobStore
  • Configuring the retention time for the Deleted Messages Vault

Enable Deleted Messages Vault by configuring Pre Deletion Hooks

By default, you need to configure a Pre Deletion Hook to let James use it. Before deleting a mail in James, PreDeletionHooks will be triggered to execute all declared hooks. If all hook executions success, then James will process to delete that mail. There is already a DeletedMessageVaultHook in James, its job is to store deleted mails into Deleted Messages Vault. Thus, you need to configure this hook in listeners.xml configuration file.

NOTE: From James 3.8.1 onward the DeletedMessageVaultHook should no longer be specified for Cassandra based products.

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

Configuring your BlobStore

The Deleted Messages Vault is using a BlobStore to store and manage the deleted messages. A BlobStore is a dedicated component to store blobs, non-indexable content. There is different implementations available for the BlobStore on top of Cassandra or file object storage services like Openstack Swift and AWS S3.

Let's consider that we want to store those deleted messages into an Openstack Swift object storage. So the configuration in the blob.properties file should look similar to this: 


implementation=s3
objectstorage.namespace=james
objectstorage.s3.endPoint=http://scality:8080/
objectstorage.s3.region=eu-west-1
objectstorage.s3.accessKeyId=accessKey1
objectstorage.s3.secretKey=verySecretKey1

If you want to dig deeper into the subject, or use an other implementation, you can find more details about this at the BlobStore Configuration page.

Configuring the retention time for the Deleted Messages Vault

To do this, you have to create a configuration file deletedMessageVault.properties, then put it into the conf directory of James. There is only one available property you may want to configure at the moment:

  • retentionPeriod: represent for the period deleted messages allowed to be stored in Deleted Messages Vault (default of one year).

Example: 


retentionPeriod=1y

More details about configuration & example can be found at Deleted Messages Vault Configuration

Deleted Messages Vault administration

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

WebAdmin Deleted Messages Vault exporting

When the administrator needs to export some user's deleted messages, you are able to choose which exporting mechanism should be used. At the moment there are two available exporting mechanisms:

  • localFile: This is a simple exporting mechanism. Through an export request, it retrieves deleted mails from Deleted Messages Vault, then store them as a zip file in James Server local file system. Then it sends a mail with the absolute path of exported file to the targeted mail address.
  • linshare: Instead of exporting blobs to the local file system, using LinShare helps you upload your blobs and people you have been sharing to can access those blobs by accessing the LinShare server and download them.

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


blob.export.implementation=localFile

You can find more details about configuration & example at Blob Export Configuration page

Example: Starting James with enabled Deleted Messages Vault by docker compose

And now to sum up everything we have seen until now and put it into practice, we will take James cassandra-rabbitmq product for the example

First, get the template cassandra-rabbitmq product configuration:


$ git clone https://github.com/apache/james-project
$ cp -rf james-project/server/apps/distributed-app/sample-configuration 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 in the previous example

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

Fourth, modify blob.properties file to configure the BlobStore that will be used and the file exporting mechanism, like we saw previously as well.

Fifth, 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/server/apps/distributed-app/docker-compose.yml

Add the following volumes for james service:


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

Then you can run it and you should have a James server with an enabled Deleted Messages Vault. You can then refer to WebAdmin documentation to create a few users, domains, mailboxes, and then connecting to it your favorite mail client to start sending messages between those users and deleting them.

And finally you can check more specifically the WebAdmin Deleted Messages Vault documentation to explore all the possibilities of the vault.