Sending an e-mail using EmailConnection

Overview

An application can use the methods of EmailConnection to describe the properties of an e-mail and submit it as a Connection API request using the SMTP protocol.

Configuration

The SMTP protocol implementation used by the EmailConnection class requires some configuration in zero.config. The minimum configuration is the identification of SMTP server to be used and this is most easily configured using a stanza along the following lines.

/config/connection/defaults/smtp/hostname = "smtp.yourdomain.com"

For more information, see the SMTP protocol documentation.

Sending a simple text e-mail

The following Java™ code extract illustrates how to send a simple text e-mail using zero.core.connection.EmailConnection:

try {
    EmailConnection email = new EmailConnection("you@projectzero.org");
    email.setFromAddress("me@projectzero.org");
    email.setSubject("Hello to you");
    email.setContent("This is the email body.");
    email.send();
} catch (Exception e) {
    // failed to send email
}

In the preceding example, the application creates a new EmailConnection and specifies the recipient's e-mail address. The mailto: prefix is added if it is not already present. The request operation is automatically set to POST.

• EmailConnection(String address)

Use the methods of EmailConnection object to set up the request headers used for an e-mail request and to specify the e-mail content. Specify the e-mail content either as a String or Reader object.

• void setFromAddress(String address)
• void setSubject(String subject)

Because the Content-Type is not specified in the example, the default, "text/plain; charset=UTF-8", is used. Alternative forms of the setContent() method are available that accept a Content-Type string as a second parameter if the application needs to specify a different value.

• void setContent(String content)
• void setContent(String content, String contentType)
• void setContent(Reader content)
• void setContent(Reader content, String contentType)

After the e-mail is prepared, the send() method is used to submit the request using the Connection API. The send() method calls the Connection.setRequestBody() and getResponse() methods, and throws an IOException or ConnectionException if the send processing fails.

• Connection.Response send()

Sending an e-mail with attachments

The EmailConnection class provides two methods to allow additional content to be sent with your e-mail:

• void addAttachment(Object attachment, String contentType, String filename)
• void addInlineContent(Object inlineContent, String contentType, String contentLocation)

Calling either of these methods causes the send() method to submit a MultipartBody object as the request body. The first Multipart.Part is the primary content specified by setContent() and the remaining parts are specified attachments and inline content.

The following example uses addAttachment() to include a separate text document as an e-mail attachment:

try {
    EmailConnection email = new EmailConnection("you@projectzero.org");
    email.setFromAddress("me@projectzero.org");
    email.setSubject("Hello to you");
    email.setContent("Please read the attachment.");
    email.addAttachment("This is the content of the attachment",
        "text/plain; charset=UTF-8",
        "attachment.txt");
    email.send();
} catch (Exception e) {
    // failed to send email
}

In the preceding example, the content of text document is specified as a String, but it is also possible to use Reader for character data, or byte[] or InputStream for binary data. Specify the appropriate content type value, including a charset parameter for character data. The final argument specifies the file name, in this case attachment.txt, that is presented when the recipient opens the e-mail.

The following example is more complex and demonstrates sending an HTML e-mail message with an inline image.

• The setContent() method is used to specify an HTML body as a String and to specify an appropriate content type.
• The image data is supplied as an InputStream, which is read from a file using the Connection API. The images/ZeroGraphic.png file is read under the current application directory, /config/root.
• The inline image is added to the e-mail using addInlineContent(), specifying the input stream, content type, and a content location. This content location matches the src attribute of the img tag in the HTML document.

try {
    EmailConnection email = new EmailConnection("you@projectzero.org");
    email.setFromAddress("me@projectzero.org");
    email.setSubject("Hello to you");
    email.setContent( "<html><p>This email has an inline image! <img src=\"images/zero.png\"></p></html>",
        "text/html; charset=UTF-8");
    InputStream imageData = Connection.doGET("file:///~/images/ZeroGraphic.png").getResponseBodyInputStream();
    email.addInlineContent(imageData, "image/png", "images/zero.png");
    email.send();
} catch (Exception e) {
    // failed to send email
}

Sending an e-mail to multiple recipients

The EmailConnection constructor allows only a single e-mail address to be specified, but the class provides a selection of methods to allow the e-mail to be sent to additional recipients. As their names suggest, addRecipient(), addCcRecipient(), and addBccRecipient() add a single "To", "Cc" and "Bcc" recipient to the e-mail.