jaystgelais / easy-mail

Easy html mail messages with automated style processing to maximize cross client rendering consistency

easy-mail

The easy-mail API provides a simple wrapper around the JavaMail APi and utilities for transforming HTML with CSS to provide greater cross client support for html email message rendering.

easy-mail accepts HTML input and performs the following transformations on it before using it for the mail message body.

1. Calculate effective styles of all elements and write them to their style attribute.
2. Remove style declarations form head of document.
3. Remove class attributes form all elements.
4. Embed all images referneces from the HTML document as relative URLs. (Fully qualified URLS will continue to link to their remote image resource)

For tips on writing effective HTML input for easy-mail please refer to this wiki page: Tips for Writing HTML Templates for Input to easy mail

Getting easy-mail

The latest easy-mail release can be downloaded directly from bintray or you can configure your build to fetch them like this (gradle example):

repositories {
	jcenter()
}

dependencies {
    compile group: 'com.github.jaystgelais', name: 'easy-mail', version: '0.2.0'
}

Using easy-mail

Suppose the following resources are available on your classpath:

/mailcontent
   |--+ MyMailMessage.html
   |--+ /css
           |--+ mail-style.css
   |--+ /images
           |--+ company-logo.jpeg

The following code would send an email based on /mailcontent/MyMailMessage.html and it's linked content.

import javax.mail.Session;
import com.github.jaystgelais.easymail.EmailMessage;
import com.github.jaystgelais.easymail.HtmlContentProvider;
import com.github.jaystgelais.easymail.URLHtmlContentProvider;
...
Session mailSession = <setup mail session>
HtmlContentProvider contentProvider
    = new URLHtmlContentProvider(getClass().getResource("./EmbeddedImageTest.html"));
EmailMessage message = new EmailMessage.Builder("[email protected]",
        "Hey check out easy-mail!", contentProvider)
    .addTo("[email protected]")
    .build();
message.send(mailSession);

Extending easy-mail

The main extension point for easy-mail is the HtmlContetProvider interface. Implementing this interface is you entry point to provided HTML content form your favorite HTML template framework.

easy-mail Versions

This project's version scheme adheres to the guidelines of Semantic Vesrioning 2.0.0.

These guidelines state that, given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

The only exception to this scheme is for version before 1.0.0. 0.x.x versions are considered experimental and allow for incompatible API changes between MINOR versions. Once version 1.0.0 is released, the rules above apply to future versions.

easy-mail's Issues

Add support for open connection to outbound smtp sever

Currently every call to EmailMessage.send(session) opens, transfers over and closes a connection. For use in a multi-threaded, multiple user environment such as a web application it would be valuable to reuse a connection or pool of connections.

Images linked as CSS background are not being enbeddef if url is relative

Add support for embedding images in body

Here's a blog post on how to do this with javax.mail

http://www.jroller.com/eyallupu/entry/javamail_sending_embedded_image_in

Add support for processing external css files from html content