Sending an email using EmailConnection

The EmailConnection class provides a simple way to send an email, including attachments.

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

See the Javadoc API reference for more information on EmailConnection and associated interfaces.

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.

Sending a simple text email

The following Java extract illustrates how to send a simple text email 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 above example, the application creates a new EmailConnection and specifies the recipient's email address. The mailto: prefix will be added if it not already present. The request operation is automatically set to POST.

The methods of EmailConnection object are used to set up the request headers used for an email request and specify the email content. The email content may be specified either as a String or Reader object.

Since the Content-Type is not specified in the example, the default, " text/plain; charset=UTF-8 ", will be used. An alternative form of the setContent() method is available that accepts a Content-Type string as a second parameter is available if the application needs to specify a different value.

Once the email has been prepared the send() method is used to submit the request using the Connection API. Under the covers, send() calls the Connection setRequestBody() and getResponse() methods and throws an IOException or ConnectionException if the send processing fails.

Sending an email with attachments

The EmailConnection class provides two methods to allow additional content to be sent with your email:

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

The following example uses addAttachment() to include a separate text document as an email 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 this example, the content of text document is specified as a String but is is also possible to use Reader for character data, or byte[] or InputStream for binary data. It is recommended that you specify the appropriate content type value including a charset parameter for character data. The final argument specifies the file name that will be presented to the user when opening the email, in this case attachment.txt

Below is a more complex example demonstrating sending an HTML email message with an inline image. There several aspects of this example that are worth noting:

• The setContent() method is used to specify an HTML body as a String and specify an appropriate content type.
• The image data is being supplied as an InputStream, which is being read from a file using the Connection API. This will read the file images/ZeroGraphic.png under the current application directory ( /config/root ).
• The inline image is added to the email 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 email to multiple recipients

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