A tutorial of using James with new Deleted Messages Vault Restoring feature

Apache James is a project about Mail Server, and in recent days, we developed an interesting feature that will help James users have a chance to restore their deleted emails. After days of discussing, we finally named it Deleted Messages Vault.

Usual restoring mechanism

In a normal mail systems, restoring emails is not a trivial jobs. When there is a request from an user to restore some of his important emails that he already deleted from the past, the administrators used to rely on the backups. But backups are never exhaustive because they are triggered at specific points in time. Second, they are not handy to use. Third, they usually are missing data but you learn it only when you need them badly. Finally, backups on a distributed system are somehow impracticable.

We now will help you get your deleted emails back!

As Apache James developers, we take care of you. We have just delivered a feature on James that provides an easy mechanism to help administrators to restore deleted emails of an user. In a brief introduction about this feature, deleted emails are retained in a specific place called Deleted Messages Vault, every time, before an email or a mailbox is going to be deleted. That email or emails belonging to that mailbox are stored in the Deleted Messages Vault, and will be used for restoring in the future if there is any request from the administrators. We already wrote a how-to article to explain about how does James store deleted emails and setup standard alone James with this feature at our official site in case you are curious.

Take a try to restore deleted emails in James

Using the default docker-compose.yml is the most simple way to start a James server. But it will be way more interesting if we can see & verify the results easily. Therefore, I’m gonna use an other easy to setup, a James- compatible application — OpenPaaS ESN. It helps you connect to James via its front end, sending & receiving emails, and many things more…

Clone OpenPaaS repository to get the docker compose file and template configurations, modify the Pre Deletion Hook configuration a bit to let James use Deleted Messages Vault, then start OpenPaaS with provisioned users by docker compose. It will start the James server automatically, you don’t have to do anything :

It will take about 30 seconds to be ready to use, there are little things you will use in the next section:

• Provisioned users include administrator (admin@open-paas.org/secret), and user0 (user0@open-paas.org/secret). We only need these two accounts to practice with Deleted Message Vault Restoring.
• Use http://localhost:8080 to access to open-paas.
• Use http://localhost:8000 to access to James WebAdmin server, where we will have our fun.

Setting up restoring deleted emails scenario

1. Logging into admin account on a browser by admin@open-paas.org/secret credentials.
2. Logging into user0 account on another different browser, or incognito window by user0@open-paas.org/secret credentials.

3. I’m gonna use admin account, send 3 emails to user0 with subjects “Mail 1”, “Mail 2”, “Mail 3”.

4. Verify that user0 received those emails.

5. Delete emails with subjects “Mail 2” and “Mail 3” (by putting them into trash, you mark the mail, then click to the trash icon at the upper right corner, then empty the trash). Now those emails are temporally stored in the Deleted Messages Vault and not available at any of user0 mailbox. The admin will help user0 to get his mails back.

6. At the moment, OpenPaaS doesn’t support the admin to use web interface for restoring emails of an user. So we will take a little effort to do it by our hands, but, it’s really simple. First, we need to retrieve James JWT token to be able to use James Web Admin restoring emails endpoint. I will use postman rather than curl for a well displayed result. Send a request

POST localhost:8080/james/api/token

with basic header authentication of the admin credential (admin@open-paas.org/secret)

7. Use that token to request James Web Admin restoring enpoint. Send a request

POST localhost:8000/deletedMessages/users/user0@open-paas.org?action=restore

with Bearer authorization header (Bearer + a space + received token). You need to pass a body message to tell James restore all messages of user0.

{
“combinator”: “and”,
“criteria”: []
}

Then, we will received an id of the task performing restoring.

8. Use task id to check the status of the task. Using an endpoint

GET localhost:8000/tasks?taskId={created task id you received}

with same authorization token before. Once, the task status is completed, we can come back to the browser and see what happened with user0's emails.

9. You can see there is a new mailbox(Restored-Messages) that appeared on user0 mailboxes, click to it, you can see that deleted emails now are available in this mailbox! User0 can be happy now.

So, that is how you use James to restore deleted emails, there would be more options for the administrators to filter out qualified emails.To better understand those options, you might want to read James Deleted Message Vault Web Admin documentation before getting your hands on it!