Mail Sender Storage API

Last modified by Admin on 2024/05/19 01:46

cogAPI to store mails and their statuses
Developed by

XWiki Development Team

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.

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 asynchronously, matching some criteria. For example to resend all mails that are in the 'prepare' state:
    #set ($mailResults = ${'state', 'prepare_%'}, 0, 0)
  • XWiki 12.9+ 

    Resend mails synchronously, matching some criteria. Interesting when there are lots of emails to resent in order not to load all emails in memory and risk an OOM:

    #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 one of:
      • prepare_success: Mail prepared successfully and ready to be sent.
      • prepare_error: Error was encountered during mail preparation, no message available for sending.
      • send_success: Mail sent with success.
      • send_error: Error was encountered during sending mail.
      • send_fatal_error: Error was encountered while retrieving mail for sending.
    • 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 = $
  • Delete all mail statuses (and associated serialized files if they exist) for all wikis in a farm, matching:
    #if ($request.confirm == '1')
      #foreach ($wiki in $
        * Deleting mail statuses for wiki [$wiki]
        #set ($currentDatabase = $xcontext.database)
        #set ($discard = $xcontext.setDatabase($wiki))
        #set ($mailStatuses = ${'state' : '%'}, 0, 0, 'state', true))
        #foreach ($mailStatus in $mailStatuses)
          ** Deleting mail status [$mailStatus.messageId] ...
          #set ($discard = $$mailStatus.batchId, $mailStatus.messageId))
        #set ($discard = $xcontext.setDatabase($currentDatabase))


The following configuration properties (from are available for this module:

  • XWiki 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


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

Get Connected