wildduck/docs/in-depth/retention-policies.md

Retention policies

Wild Duck IMAP server has retention support built in. This means that messages that have been stored in a mailbox for a defined amount of time are deleted automatically.

All Spam and Trash folders have a maximum retention time set to 30 days, other folders do not have retention time set by default.You can set the retention time when creating users via HTTP API using the retention property. It is a numeric field that if set, causes all mailboxes of the user to have a retention time of the value in milliseconds.

Once retention time is reached, the message is deleted from database and attachment references are decremented.

Spam and Trash folders can not have longer than 30 days of retention, so if you use a larger value it is capped at 30 days

For example if you want to have a default retention policy of 90 days, then use 7776000000 as the retention value (90 * 24 * 3600 * 1000). If defined then this value also applies to any new folders the user creates.

curl -XPOST "http://localhost:8080/user" -H 'content-type: application/json' -d '{
  "username": "testuser",
  "password": "secretpass",
  "retention": 7776000000
}'

You can change the retention with the Mailbox Update API. Updating retention policy for a mailbox does not change retention time for existing messages, it only applies to new messages.

How does it work?

All Wild Duck instances (this means processes) periodically try to get a lock for cleaning up expired messages. If a lock is acquired then this instance starts cleanup process by creating a cursor to list all messages that have retention time set older than current time. This cursor is then used to delete expired messages one by one. This also means that a message might be available a bit longer than retention time, it is not deleted exactly the time retention time kicks in but sometime later (in most cases within a minute).

A lot of things happen when a message is deleted:

• the message entry is removed from the messages collection
• IMAP clients are notified about the expunged message
• Quota usage counter is updated in users collection
• Reference counters for linked attachments are decremented (attachments in Wild Duck are de-duplicated which means that only the first copy of an identical attachment is stored in database)

A separate process then finds all attachments that have zero references and deletes these.