API to store mails and their statuses

Description

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.

This modules offers a scripting API:

• Resend a failed mail (The returned object is documented in the Mail Sender API):
  #set ($mailResult = $services.mail.storage.resend(batchId, messageId))
• Resend a failed mail asynchronously:
  #set ($mailResult = $services.mail.storage.resendAsynchronously(batchId, messageId))
• Resend mails asynchronously, matching some criteria. For example to resend all mails that are in the 'prepare' state:
  #set ($mailResults = $services.mail.storage.resendAsynchronously({'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 = $services.mail.storage.resend({'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 = $services.mail.storage.load($filterMap, $offset, $count)

  where:

  • 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 = $services.mail.storage.delete(batchId, messageId))
• Delete all mail statuses from a batch, and their associated serialized mails on the file system (if any):
  #set ($mailResult = $services.mail.storage.delete(batchId))
• Delete all messages having a status in the database and their serialized messages on the file system:
  #set ($mailResult = $services.mail.storage.deleteAll())
• Delete all mail statuses (and associated serialized files if they exist) for all wikis in a farm, matching:
  {{velocity}}
  #if ($request.confirm == '1')
    #foreach ($wiki in $services.wiki.allIds)
      * Deleting mail statuses for wiki [$wiki]
      #set ($currentDatabase = $xcontext.database)
      #set ($discard = $xcontext.setDatabase($wiki))
      #set ($mailStatuses = $services.mail.storage.load({'state' : '%'}, 0, 0, 'state', true))
      #foreach ($mailStatus in $mailStatuses)
        ** Deleting mail status [$mailStatus.messageId] ...
        #set ($discard = $services.mail.storage.delete($mailStatus.batchId, $mailStatus.messageId))
      #end
      #set ($discard = $xcontext.setDatabase($currentDatabase))
    #end
  #end
  {{/velocity}}

Configuration

The following configuration properties (from xwiki.properties) 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

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

• org.xwiki.platform:xwiki-platform-mail-send-api 16.9.0
• org.xwiki.platform:xwiki-platform-mail-send-default 16.9.0
• org.xwiki.platform:xwiki-platform-oldcore 16.9.0
• org.xwiki.commons:xwiki-commons-script 16.9.0