com.xpn.xwiki.plugin.mailsender
Interface MailSender

All Known Implementing Classes:

MailSenderPluginApi

public interface MailSender

Send mails to recipients (to, cc, bcc). Both text and HTML emails can be sent along with attachments. Also support XWiki page templates and allows sending a collection of emails in one call.

Version:

$Id$

Method Summary

Mail	createMail() A helper method for Velocity scripts since we cannot create Java objects from Velocity.
MailConfiguration	createMailConfiguration(XWiki xwiki) A helper method for Velocity scripts since we cannot create Java objects from Velocity.
int	sendHtmlMessage(String from, String to, String cc, String bcc, String subject, String body, String alternative, List<Attachment> attachments) Sends an HTML mail, with a list of attachments
int	sendMail(Mail mail) Generic method for sending emails.
int	sendMail(Mail mail, MailConfiguration mailConfiguration) Generic method for sending emails.
int	sendMessageFromTemplate(String from, String to, String cc, String bcc, String language, String documentFullName, org.apache.velocity.VelocityContext vcontext) Uses an XWiki document to build the message subject and context, based on variables stored in the VelocityContext.
int	sendRawMessage(String from, String to, String rawMessage) Sends a raw message.
int	sendTextMessage(String from, String to, String subject, String message) Sends a simple text plain mail
int	sendTextMessage(String from, String to, String cc, String bcc, String subject, String message, List<Attachment> attachments) Sends a simple text plain mail with a list of files attachments

Method Detail

createMail

Mail createMail()

A helper method for Velocity scripts since we cannot create Java objects from Velocity.

Returns:

An empty mail message to be populated with recipient addresses, subject, message, etc.

createMailConfiguration

MailConfiguration createMailConfiguration(XWiki xwiki)

A helper method for Velocity scripts since we cannot create Java objects from Velocity.

Parameters:

xwiki - the XWiki object used to get the default values from the XWiki Preferences ("smtp_server" and "smtp_from").

Returns:

A mail server configuration, initialized with values from XWiki Preferences, but which can be overriden by users.

sendMail

int sendMail(Mail mail)

Generic method for sending emails. The passed Mail object has to be populated by the caller to set the correct fields. All the other sendHtmlXXX() and sendTextXXX() methods are specialized helper versions of this generic method.

Parameters:

mail - the already populated mail Object to be sent

Returns:

0 on success, -1 on failure. On failure the error message is stored in the XWiki context under the "error" key.

sendMail

int sendMail(Mail mail,
             MailConfiguration mailConfiguration)

Generic method for sending emails. The passed Mail object has to be populated by the caller to set the correct fields. The passed Mail Configuration allows the user to override the default connection properties (SMTP host, SMTP port, SMTP from, etc). All the other sendHtmlXXX() and sendTextXXX() methods are specialized helper versions of this generic method.

Parameters:

mail - the already populated mail Object to be sent

mailConfiguration - the configuration to use

Returns:

0 on success, -1 on failure. On failure the error message is stored in the XWiki context under the "error" key.

sendHtmlMessage

int sendHtmlMessage(String from,
                    String to,
                    String cc,
                    String bcc,
                    String subject,
                    String body,
                    String alternative,
                    List<Attachment> attachments)

Sends an HTML mail, with a list of attachments

Parameters:

to - the recipient of the message

from - the sender

cc - carbon copy

bcc - hidden carbon copy

subject - the subject of the message

body - the body content of the mail

alternative - the alternative text offered to the mail client

attachments - List of com.xpn.xwiki.api.Attachment that will be attached to the mail.

Returns:

0 on success, -1 on failure. On failure the error message is stored in the XWiki context under the "error" key.

sendTextMessage

int sendTextMessage(String from,
                    String to,
                    String subject,
                    String message)

Sends a simple text plain mail

Parameters:

to - the recipient of the message

from - the sender

subject - the subject of the message

message - the body of the message

Returns:

0 on success, -1 on failure. On failure the error message is stored in the XWiki context under the "error" key.

sendTextMessage

int sendTextMessage(String from,
                    String to,
                    String cc,
                    String bcc,
                    String subject,
                    String message,
                    List<Attachment> attachments)

Sends a simple text plain mail with a list of files attachments

Parameters:

to - the recipient of the message

from - the sender

cc - carbon copy

bcc - hidden carbon copy

subject - the subject of the message

message - the body of the message

attachments - List of com.xpn.xwiki.api.Attachment that will be attached to the mail.

Returns:

0 on success, -1 on failure. On failure the error message is stored in the XWiki context under the "error" key.

sendRawMessage

int sendRawMessage(String from,
                   String to,
                   String rawMessage)

Sends a raw message. The message can contain additional headers at the start, which are parsed and correctly sent as additional headers (Bcc, Subject, Reply-To, etc.). The actual message is treated as plain text.

Parameters:

from - the sender

to - the receiver

rawMessage - the raw message, containing additional headers and the actual message

Returns:

0 on success, -1 on failure. On failure the error message is stored in the XWiki context under the "error" key.

sendMessageFromTemplate

int sendMessageFromTemplate(String from,
                            String to,
                            String cc,
                            String bcc,
                            String language,
                            String documentFullName,
                            org.apache.velocity.VelocityContext vcontext)

Uses an XWiki document to build the message subject and context, based on variables stored in the VelocityContext. Sends the email.

Parameters:

from - Email sender

to - Email recipient

cc - Email Carbon Copy

bcc - Email Hidden Carbon Copy

language - Language of the email

documentFullName - Full name of the template to be used (example: XWiki.MyEmailTemplate). The template needs to have an XWiki.Email object attached

vcontext - Velocity context passed to the velocity renderer

Returns:

0 on success, -1 on failure. On failure the error message is stored in the XWiki context under the "error" key.