cogAPI to store mails and their statuses
Developed by

XWiki Development Team

Active Installs0
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager


This module uses the Mail Sender API and is used by the Mail Application modules to:

  • Persist the statuses of email sent into the Database and display the statuses of all mails in the Mail Admin UI. This happens automatically whenever the user uses a Database Mail Listener when sending emails.
  • Serialize the mails sent on the file system so that when they fail to be sent, they can be resent later on. There's a UI to resend mails in the Mail Application too.
  • At XWiki startup, automatically resend mails that weren't sent yet (i.e. mails in the prepare state) New in XWiki 9.3RC1

The way to access the mail sender API from script has changed in XWiki 12.4RC1. Before that version you had to use $services.mailstorage, where the new way is $

This modules offers a scripting API:

  • Resend a failed mail (The returned object is documented in the Mail Sender API):
    #set ($mailResult = $, messageId))
  • Resend a failed mail asynchronously:
    #set ($mailResult = $, messageId))
  • Resend mails matching some criteria. For example to resend all mails that are in the 'prepare' state:
    #set ($mailResults = ${'state', 'prepare_%'}, 0, 0)
  • Load mail statuses:
    ## The map contains the status criteria to use for loading the statuses from the database. You can specify from 0 to N map parameters.
    #set ($filterMap = { 'id' : "<mail id>", 'batchId' : "<batch id>", 'state' : "<state>", 'date' : "<date>", 'recipients' : "<recipients>", 'type' : "<type>", 'errorSummary' : "<error summary>", 'errorDescription' : "<error description>", 'wiki' : "<wiki>" }
    #set ($mailStatuses = $$filterMap, $offset, $count)


    • id: the unique id of the mail
    • batchId: the unique batch id representing the batch in which the mail was sent
    • state: can be failed, sent or ready
    • date: the sent date
    • recipients: the comma-separated list of recipients for the mail
    • type: the type of mail (e.g. "Account Validation", "Watchlist", "Reset Password", etc)
    • errorSummary: short summary of the problem when the mail has failed to be sent
    • errorDescription: long description of the problem when the mail has failed to be sent (usually a stack trace)
    • wiki: the wiki in which the mail was sent
  • Delete a single mail status and associated serialized mail on the file system (if any):
    #set ($mailResult = $, messageId))
  • Delete all mail statuses from a batch, and their associated serialized mails on the file system (if any):
    #set ($mailResult = $
  • Delete all messages having a status in the database and their serialized messages on the file system:
    #set ($mailResult = $


The following configuration properties are available for this module:

#-# [Since 6.4.1, 7.0M1]
#-# When using the Database Mail Listener, whether mail statuses for mails that have been sent successfully must be
#-# discarded or not. They could be kept for tracability purpose for example.
#-# The default is:
# mail.sender.database.discardSuccessStatuses = true

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.


Dependencies for this extension (org.xwiki.platform:xwiki-platform-mail-send-storage 12.8):

Tags: mail
Created by Vincent Massol on 2020/05/11 15:36

Get Connected