Mandrill SMTP (Simian Mail Transfer Protocol)

Does sending emails from your java program have you red in the face? Mandrill’s red on the other end but they’ll take care of your emails and take the stress off of you.
The java wrapper for the Mandrill web service allows your java application to use a powerful REST-based email web service with a powerful and rapidly increasing feature set.

You can download the wrapper here.

This wrapper is currently in its alpha stage; there is ongoing development within the Mandrill API during its beta testing and features may stop working if the request/response format is changed on the Mandrill side. It is my intent to keep this as up to date as possible and willbe releasing a tagged version once the 1.0 API is made final.

Urls

This feature of the web service keeps track of important usage data in regard to the URLs used within your emails. Mandrill assigns a unique ID to each URL and keeps track of things like the number of times it was sent, how many times it was clicked, and how many of those clicks were unique. Mandrill also  keeps track of your links over time periods and lets you knowboth which are most active and which are most actively used in sent emails.

User Management

Mandrill offers a rich suite of user management and reporting tools that allow you to monitor performance of your users in regard to email campaigns.

Message sending

Mandrill allows sending of both one-off and templated emails with instant feedback about the status of the sent messages.

Templates

Templates allow you to create the body of an email and dynamically swap out portions tailored specifically to the user(s)you’re targeting allowing for a more personalized look and feel.

Use of the java wrapper is relatively easy and you could be up and running quickly. The wrapper was designed to be agnostic to any framework so it could apply to the widest audience. At the same time, not binding it to any one particular framework keepsits jar file from being unnecessarily large. Along the same lines, all debug/log statements are currently using System.out rather than a logging framework. I plan on including slf4j implemented with logback in the release version.

Examples of usage of the wrapper are in the src/it/java folder and rely on a properties file that must be created and be made available on the classpath called mandrill.properties The info in this properties file is only used during integration testing. The properties file needs the following fields:

#(replace the values to the right of the equals sign)
apiKey=Your Mandrill API key
email.from=email address you’ve set up in the Mandrill interface that is verified for sending
email.to.name1=Name of someone to email
email.to.address1=Email address of the person listed above
email.to.name2=Name of someone else to email
email.to.address2=Email address of the person listed above
verify.email=Email address of someone to verify on your Mandrill account

The integration tests use explicit configuration directly in java source rather than leveraging a framework. “But I don’t feel like doing all of that” you might say. I’d say you’re in luck because the wrapper was designed to support IoC frameworkssuch as spring. We’ll go over that next.

Spring configurationThere’s an example skeleton Spring configuration located at src/main/resources/spring/mandrillConfig.xml. This file is not well-formed and can’t be imported as is; you’ll need to copy the contents of this into your application’s spring configuration file. The only configuration you’ll need to do within these elements is within the MandrillConfiguration declaration. You may also change the names of the beans if you’d like.
All of the elements you’ll need to construct Mandrill Requests are available inside the com.cribbstechnologies.clients.mandrill.model package. The parent class for almost all elements in this package is BaseMandrillRequest which holds the api key. It’s not necessary to set the api key manually as it’s injected before the request is posted to the web service.
MandrillRESTRequest is the class that does all of the heavy lifting. It uses Jackson to marshall the model objects to JSON,opens a http connection using apache HttpClient, retrieves the response and again uses Jackson to marshall the JSON responseback to model objects.

I’ll be making another post in the near future with a spring-enabled test application.