The Carbon e-Mail Module

Purpose

The Email Service has been designed to provide projects with simple APIs for sending mails synchronously, using SMTP. Packaged on top of the basic JavaMail API, this service allows sending mails to one or many people, in text or HTML format, with or without attachments.

Component Configuration

Typical Email Component Configuration looks like the following:

<Configuration ConfigurationInterface="org.sape.carbon.services.email.MailConfiguration">
    <FunctionalImplementationClass>org.sape.carbon.services.email.SynchronousMailService</FunctionalImplementationClass>
    <FunctionalInterface>org.sape.carbon.services.email.MailService</FunctionalInterface>
    <SmtpHost>relaymail.xyz.com</SmtpHost>
</Configuration>

Configuration parameters for StatementConfiguration

Property	Data Type / Value	Description
ConfigurationInterface	org.sape.carbon.services.email.MailConfiguration	Defines the configuration Interface for a statement.
FunctionalInterface	org.sape.carbon.services.email.MailService	Functional Interface defines the programming contract.
FunctionalImplementation	org.sape.carbon.services.email.SynchronousMailService	Implementation for this service.
SmtpHost	relaymail.xyz.com	The name or IP address of the smtp server.
HoldConnection	Optional, true or false. Defaulted to false	A boolean property indicating whether or not email service will create and keep open a connection to the smtphost for it's lifetime. If set to true the connection will not be closed until the email service is shutdown. If set to false a new connection will be opened for each email sent.
RetryAttempts	Optional, Defaulted to 0	This indicates the number of retry attempts to be made with smtp server to send an email. When trying to send an email the service may receive an exception back from JavaMail. This is usually the result of failure to connect to the email server. In this case the service will execute the following steps $RetryAttempts times. Close the connection to the email server Sleep for $SleepTimeInMilliSecs Reopen the connection to the email server Try to send the email again
SleepTimeInMilliSecs	Optional, Defaulted to 500 (0.5 secs)	Time in milliseconds waited between send attempts when failure occurs. If the $RetryAttempts are 0 then this property is not required.

Examples

Sending mail to one reciepient:

import org.sape.carbon.services.email.util.classify.MailContentTypeEnum;
import org.sape.carbon.services.email.MailFailureException;
import org.sape.carbon.services.email.MailDataObject;
...

// Obtain a reference of the email component from the Lookup service 

MailService mail = (MailService) Lookup.getInstance().fetchComponent("/email/test");

try {
    MailDataObject mailDataObject = new MailDataObject();
    mailDataObject.addTo("Someone@somewhere.com", "Someone");
    mailDataObject.setFrom("joe@xyz.com", "Joe");
    mailDataObject.setSubject("subject");

    mailDataObject.setBody("A simple plain text email", MailContentTypeEnum.PLAIN_TEXT);
    mail.sendMail(mailDataObject);

} catch(MailFailureException me) {
// handle Failure
}

Sending email to multiple recipients:

import org.sape.carbon.services.email.MailFailureException;
import org.sape.carbon.services.email.util.MailAttachment;
...

// Obtain a reference of the email component from the Lookup service 
MailService mail = (MailService) Lookup.getInstance().fetchComponent("/email/test");

// Prepare "To" List, it is mandatory 
HashMap toMap = new HashMap();
toMap.put("Someone@somewhere.com", "Someone");

Prepare CC list, it can be null
HashMap ccMap = new HashMap();
ccMap.put("ccSomeone@somewhere.com", "ccSomeone");

// Prepare BCC list, it can be null
HashMap bccMap = null;

try {

    MailDataObject mailDataObject = new MailDataObject();
    mailDataObject.addTo(toMap);
    mailDataObject.addCC(ccMap);
    mailDataObject.addBCC(bccMap);
    mailDataObject.setFrom("joe@xyz.com", "Joe");
    mailDataObject.setSubject("subject");
    mailDataObject.addHeader("X-MailService", "XYZ Corporation");
    mailDataObject.setBody("A simple plain text email", MailContentTypeEnum.PLAIN_TEXT);
    mail.sendMail(mailDataObject);
} catch(MailFailureException me) {
// handle failure
}

Sending email with attachments:

import org.sape.carbon.services.email.MailFailureException;
import org.sape.carbon.services.email.util.MailAttachment;
...
// Obtain a reference of the email component from the Lookup service 
MailService mail = (MailService) Lookup.getInstance().fetchComponent("/email/test");

// Prepare "To" List, this is mandatory
HashMap toMap = new HashMap();
toMap.put("Someone@somewhere.com", "Someone");

// Prepare CC list, can be null
HashMap ccMap = new HashMap();
ccMap.put("ccSomeone@somewhere.com", "ccSomeone");

// Prepare BCC list, can be null
HashMap bccMap = null;

// Any extra headers, can be null

HashMap headers = new HashMap();
headers.put("X-MailService", "XYZ Corporation");

// Charset for encoding e.g ISO-8859-1, UTF-8.
// if null is passed default encoding is used
String charset = null;
try {
    // Adding attachments
    MailAttachment[] attachments = new MailAttachment[2];
    attachments[1] = new MailAttachment("Name", "description", "c:\\attachment.txt");

    // Add import statement java.net.URL
    URL url = new URL("http", "localhost", "attachment.txt");
    attachments[2] = new MailAttachment("Name", null, url);

    MailDataObject mailDataObject = new MailDataObject();
    mailDataObject.addTo(toMap);
    mailDataObject.addCC(ccMap);
    mailDataObject.addBCC(bccMap);
    mailDataObject.setFrom("joe@xyz.com", "Joe");
    mailDataObject.setSubject("subject");
    mailDataObject.setBody(
        "<html><body><b>This message should be in bold</html></body></b>",
    MailContentTypeEnum.HTML);
    mailDataObject.setAttachments(attachments);
    mail.sendMail(mailDataObject);
} catch(MalformedURLException mue) {
    // handle failure 
} catch(MailFailureException me) {
    // handle failure 
}

Sending internationalized emails:

import org.sape.carbon.services.email.MailFailureException;
import org.sape.carbon.services.email.util.MailAttachment;
...
// Obtain a reference of the email component from the Lookup service 
MailService mail = (MailService) Lookup.getInstance().fetchComponent("/email/test");

// Prepare "To" List, it is a mandatory field 
HashMap toMap = new HashMap();
toMap.put("Someone@somewhere.com", "Someone");

// Charset for encoding
String charset = "UTF-8";

String nonASCIICharacters = "ôôôôô";
String localizedFromPersonal = nonASCIICharacters;
String fromEmail = "joe@xyz.com";
String localizedSubject = nonASCIICharacters;
String localizedBody = nonASCIICharacters;
String body = "<html><body><b>" + localizedBody + "</html></body></b>";

// Note headers cannot be internationalized
Map headers = null;

try {
    MailDataObject mailDataObject = new MailDataObject();
    mailDataObject.addTo(toMap);
    mailDataObject.setFrom("joe@xyz.com", localizedFromPersonal);
    mailDataObject.setSubject(localizedSubject);
    mailDataObject.setBody(body, MailContentTypeEnum.HTML);
    mailDataObject.setCharset(charset);
    mail.sendMail(mailDataObject);
}
catch(MailFailureException me) {
// handle failure
}