Tuesday, August 18, 2009

Sending HTML Email with embedded Images using Apache Commons EMail

Sometimes we would like to send emails that have better looking and are more rich in their content. Today’s most email clients know to show HTML email content. That means that the body of the email is actually HTML rather than plain text. Sending HTML emails is quite simple and can be done using Apache Commons Email. Here is an example class built on Apache Commons Email that sends HTML email:

package com.bashan.blog.mail;
import org.apache.commons.mail.EmailException;
import org.apache.commons.mail.HtmlEmail;
public class Mailer {
  protected String host;
  protected String username = null;
  protected String password = null;
  protected boolean isTLS = false;
  public Mailer(String host, String username, String password, boolean isTLS) {
    this.host = host;
    this.username = username;
    this.password = password;
    this.isTLS = isTLS;
  }
  public Mailer(String host, String username, String password) {
    this(host, username, password, false);
  }
  public Mailer(String host) {
    this(host, null, null, false);
  }
  public void sendHTMLMail(String fromEmail,
                           String fromName,
                           String[] toEmail,
                           String[] toName,
                           String subject,
                           String html,
                           String alternateText) throws EmailException {
    HtmlEmail email = new HtmlEmail();
    email.setHostName(host);
    email.setFrom(fromEmail, fromName);
    for (int i = 0; i < toEmail.length; i++) {
      email.addTo(toEmail[i], toName[i]);
    }
    if (username != null) {
      email.setAuthentication(username, password);
    }
    email.setTLS(isTLS);
    email.setSubject(subject);
    email.setHtmlMsg(html);
    email.setTextMsg(alternateText);
    email.send();
  }
}

In order to use this code, make sure to put “commons-email.jar” as well as “mail.jar” (Java mail) in your class path. The latest version of “mail.jar” can be easily found by searching “java mail” in Google and downloading from Sun web site.

Note that the method “sendHTMLMail” contains property named: “alternateText”. This property is used for mail clients that does not support receiving HTML mails.

Suppose we would like to make our HTML email look better and add some image to it. We don’t want the image to be sent as a regular attachment. We would like the image to be embedded in our HTML mail message by using the image tag (img).

Luckily, Apache Commons Email supplies a simple way of doing it by using the “embed” method. For example, in order to embed an image that is placed in some URL we can do:

String id = email.embed(new URL("http://server.com/someimage.png"), "Example");

Note that “embed” method takes 2 arguments. First is the URL pointing to the image location and second is the image name. Note also that the “embed” method returns a String id. This id is used as a reference to the image embedded in the mail message. For example, our HTML mail message can look like:

email.setHtmlMsg("<html><body><image src='cid:" + id + "'></body></html>");

Note that the embedded image is referenced by using the prefix: “cid:” in the image “src” property.

As you can see, the embed method returns an id that is being later used in the construction of the HTML. this makes it a bit harder embedding images in HTML mail messages, since we don’t know the id of the embedded image when passing the HTML code as an argument. We can easily solve this problem by defining our own convention of referencing the embedded images that will later will be replaced with the proper id. Our convention will be: Each embed resource which we would like to embed in our HTML code will be named:

${resource number}

For example, suppose we would like to embed a single image. our HTML code will look like:

<html><body><img src='${0}' /></body></html>

Where the: ${0} means, we would like to put our first image in the “src” property.

Support we have 2 images that we want to use 4 times in our HTML. For example:

<html>
  <body>
    <img src='${0}' />
    <img src='${1}' />
    <img src='${0}' />
    <img src='${1}' />
  </body>
</html>

In this example we want to embed in our HTML 2 images and show them one after another twice. Of course that in the code, we will make sure to replace all the occurrences with: ${resource number} with the proper id of the embedded image.

Since an embedded resource is actually defined by 2 parameters: URL and name, we will define an inner static class that will represent a resource. This class is named: Resource. The class is pretty straight forward and need no explanations. An array of this class will be used for passing our method as many resources as we would like to embed in our HTML mail message. Of course that the “resource number” signifies the position of the resource we would like to embed in our Resources array. For example: “${3}” means we would like to embed the 4th resource from our resources array.

We can now have a look at our complete “sendHTMLMail” method that also knows to send multiple embedded resources along with the HTML mail message. Note that the old method for sending HTML mails without resources is still supported:

package com.bashan.blog.mail;
import org.apache.commons.mail.EmailException;
import org.apache.commons.mail.HtmlEmail;
import java.net.MalformedURLException;
import java.net.URL;
public class Mailer {
  protected String host;
  protected String username = null;
  protected String password = null;
  protected boolean isTLS = false;
  public Mailer(String host, String username, String password, boolean isTLS) {
    this.host = host;
    this.username = username;
    this.password = password;
    this.isTLS = isTLS;
  }
  public Mailer(String host, String username, String password) {
    this(host, username, password, false);
  }
  public Mailer(String host) {
    this(host, null, null, false);
  }
  public void sendHTMLMail(String fromEmail,
                           String fromName,
                           String[] toEmail,
                           String[] toName,
                           String subject,
                           String html,
                           String alternateText,
                           Resource[] resources) throws EmailException {
    HtmlEmail email = new HtmlEmail();
    email.setHostName(host);
    email.setFrom(fromEmail, fromName);
    for (int i = 0; i < toEmail.length; i++) {
      email.addTo(toEmail[i], toName[i]);
    }
    if (username != null) {
      email.setAuthentication(username, password);
    }
    if (resources != null) {
      int i = 0;
      for (Resource resource : resources) {
        String id = email.embed(resource.getUrl(), resource.getName());
        html = html.replaceAll("\\$\\{" + i++ + "\\}", "cid:" + id);
      }
    }
    email.setTLS(isTLS);
    email.setSubject(subject);
    email.setHtmlMsg(html);
    email.setTextMsg(alternateText);
    email.send();
  }
  public void sendHTMLMail(String fromEmail,
                           String fromName,
                           String[] toEmail,
                           String[] toName,
                           String subject,
                           String html,
                           String alternateText) throws EmailException {
    sendHTMLMail(fromEmail, fromName, toEmail, toName, subject, html, alternateText, null);
  }
  public static class Resource {
    private URL url;
    private String name;
    public Resource(URL url, String name) {
      this.url = url;
      this.name = name;
    }
    public Resource(String url, String name) throws MalformedURLException {
      this(new URL(url), name);
    }
    public URL getUrl() {
      return url;
    }
    public void setUrl(URL url) {
      this.url = url;
    }
    public String getName() {
      return name;
    }
    public void setName(String name) {
      this.name = name;
    }
  }
  public static void main(String[] args) throws Exception {
    new Mailer("smtp.gmail.com", "youruser@gmail.com", "yourpassword", true).sendHTMLMail(
        "admin@test.com", "Tester", new String[]{"guy.bashan@gmail.com"}, new String[]{"Guy Bashan"}, "Testing HTML Email",
        "<html><body><table><tr><td>Image 1</td><td>Image 2</td></tr><tr><td>" +
            "<img src='${0}'/></td><td><img src='${1}'/></td></tr></table></body></html>", "alternate HTML",
        new Resource[]{new Resource("http://www.google.com/intl/en_ALL/images/logo.gif", "Google Logo 1"),
            new Resource("http://www.google.com/intl/en_ALL/images/logo.gif", "Google Logo 2")});
  }
}

In the bottom of the Mailer class you can find a small test program that sends HTML mail message with 2 embed images of Google logo.

No comments:

Post a Comment