Mail Sender Plugin

Last modified by Vincent Massol on 2021/03/17 21:29

cogAPI to send emails
TypePlugin
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Enterprise, XWiki Enterprise Manager, XWiki Watch

Description

Starting with XWiki 6.4, this plugin is now replaced by the Mail Sender API.

Installation

To use, add the com.xpn.xwiki.plugin.mailsender.MailSenderPlugin plugin definition to the xwiki.plugins property in your xwiki.cfg file (this definition is already there if you use XWiki Enterprise 1.2 Milestone 2 or above).

The API is the following: 

/**
     * Sends an HTML mail, with a list of attachments
     *
     * @param to the recipient of the message
     * @param from the sender
     * @param cc carbon copy
     * @param bcc hidden carbon copy
     * @param subject the subject of the message
     * @param body the body content of the mail
     * @param alternative the alternative text offered to the mail client
     * @param attachments List of com.xpn.xwiki.api.Attachment that will be attached to the mail.
     * @return 0 on success, -1 on failure. on failure the error message is stored in XWiki context
     */
    public int sendHtmlMessage(String from, String to, String cc, String bcc, String subject, String body, String alternative, List attachments);

    /**
     * Sends a simple text plain mail
     *
     * @param to the recipient of the message
     * @param from the sender
     * @param subject the subject of the message
     * @param message the body of the message
     * @return 0 on success, -1 on failure. on failure the error message is stored in XWiki context
     */
    public int sendTextMessage(String from, String to, String subject, String message);

    /**
     * Sends a simple text plain mail with a list of files attachments
     *
     * @param to the recipient of the message
     * @param from the sender
     * @param cc carbon copy
     * @param bcc hidden carbon copy
     * @param subject the subject of the message
     * @param message the body of the message
     * @param attachments List of com.xpn.xwiki.api.Attachment that will be attached to the mail.
     * @return 0 on success, -1 on failure. on failure the error message is stored in XWiki context
     */
    public int sendTextMessage(String from, String to, String cc, String bcc, String subject, String message, List attachments);

    /**
     * Uses an XWiki document to build the message subject and context, based on variables stored in
     * the VelocityContext. Sends the email.
     *
     * @param from Email sender
     * @param to Email recipient
     * @param cc Email Carbon Copy
     * @param bcc Email Hidden Carbon Copy
     * @param language Language of the email
     * @param documentFullName Full name of the template to be used (example:
     * XWiki.MyEmailTemplate). The template needs to have an XWiki.Email object attached
     * @param vcontext Velocity context passed to the velocity renderer
     * @return True if the email has been sent
     */
    public int sendMessageFromTemplate(String from, String to, String cc, String bcc, String language, String documentFullName, VelocityContext vcontext);

Example

For the Send Page By Email Application, the Mail Sender Plugin has been used to provide the application's backend. 

The application uses the sendHtmlMessage method to send an email that includes the page's rendered content :

#set($emailrecipient = "$request.recipient") ## The recipient's email as entered in the form.
#set($emailcc = "$request.cc") ## CC recipients' emails as entered in the form.
#set($emailbcc = "$request.bcc") ## BCC recipients' emails as entered in the form.
#set($emailcomment = "$request.comment") ## The contents of the form's comment field

#if($emailcc != "")
#set($testcc = "$emailcc")   ## Checks that the CC field isn't empty (this would throw an exception), replaces it with a null value if it is.
#else
#set($testcc = $xwiki.null)
#end

#if($emailbcc != "")
#set($testbcc = "$emailbcc")   ## Checks that the BCC field isn't empty (this would throw an exception), replaces it with a null value if it is.
#else
#set($testbcc = $xwiki.null)
#end

$xwiki.mailsender.sendHtmlMessage(
"$context.user",              ## Sets the sender as being the current user.
"$emailrecipient",            ## Sets the email recipient's address.
$testcc,                      ## Sets the email CC recipients' addresses.
$testbcc,                     ## Sets the email BCC recipients' addresses.
"Page : $doc.name",           ## Sets the page name as the email's subject.
$emailcontent,                ## Sets the email's content as defined in a previous variable.
$doc.getContent(),            ## Sets the email's alt field as being the page's wiki markup content (for email clients that do not support HTML).
$doc.getAttachmentList())     ## Adds the page attachments to the email.

Result

You can see the resulting emails on the Send Page By Email Application page.

Tags: plugin mail
    

Get Connected