Lutung - A Java Mandrill API Connector
Java
Latest commit 33bd6ec Aug 24, 2016 @billoneil billoneil committed on GitHub Merge pull request #69 from RomaLefrancois/master
HTTPClient usage improvement

README.md

Lutung - Java Mandrill API

Join the chat at https://gitter.im/rschreijer/lutung

Lutung - a Java interface to the Mandrill API. Check out Mandrill's API Documentation to see all the possible magic.

Features:

  • all public API calls are implemented.
  • easy library set up; just provide your api key that you got from Mandrill.
  • all API calls are exposed through one simple interface: the MandrillApi class.
  • easy, intuitive naming scheme. All function-names are derived from the Mandrill API calls: if there is a call with the address '/messages/send.json', then we have a function for that called 'MandrillApi.messages().send(...)'.
  • API request errors are exposed to the user (you!) as a MandrillApiError.

Installation

If you're using Maven, just add this dependency to your pom.xml:

<dependency>
    <groupId>com.mandrillapp.wrapper.lutung</groupId>
    <artifactId>lutung</artifactId>
    <version>0.0.7</version>
</dependency>

If you're not using Maven, see Dependencies below.

Examples

The 'whoami' of Mandrill:

MandrillApi mandrillApi = new MandrillApi("<put ur Mandrill API key here>");

MandrillUserInfo user = mandrillApi.users().info();

// pretty-print w/ gson
Gson gson = new GsonBuilder().setPrettyPrinting().create();
System.out.println( gson.toJson(user) );

Send a 'Hello World!' email

MandrillApi mandrillApi = new MandrillApi("<put ur Mandrill API key here>");

// create your message
MandrillMessage message = new MandrillMessage();
message.setSubject("Hello World!");
message.setHtml("<h1>Hi pal!</h1><br />Really, I'm just saying hi!");
message.setAutoText(true);
message.setFromEmail("kitty@yourdomain.com");
message.setFromName("Kitty Katz");
// add recipients
ArrayList<Recipient> recipients = new ArrayList<Recipient>();
Recipient recipient = new Recipient();
recipient.setEmail("claireannette@someotherdomain.com");
recipient.setName("Claire Annette");
recipients.add(recipient);
recipient = new Recipient();
recipient.setEmail("terrybull@yetanotherdomain.com");
recipients.add(recipient);
message.setTo(recipients);
message.setPreserveRecipients(true);
ArrayList<String> tags = new ArrayList<String>();
tags.add("test");
tags.add("helloworld");
message.setTags(tags);
// ... add more message details if you want to!
// then ... send
MandrillMessageStatus[] messageStatusReports = mandrillApi
        .messages().send(message, false);

Error handling for Mandrill API errors

MandrillApi mandrillApi = new MandrillApi("<put ur Mandrill API key here>");

try {
    MandrillUserInfo user = mandrillApi.users().info();
} catch(final MandrillApiError e) {
    log.error(e.getMandrillErrorAsJson(), e);
}

Create a new template

MandrillApi mandrillApi = new MandrillApi("<put ur Mandrill API key here>");

MandrillTemplate newTemplate = mandrillApi.templates().add(
        "test_template_001", 
        "<html><body><h1>Hello World!</h1></body></html>",
        false);

Dependencies

If you're not using Maven, here's a list of dependencies. Just make sure these jar files are on your classpath:

Known Issues

  • The metadata returned by the mandrill api on /messages/search.json does not get mapped to a member of MandrillMessageInfo

  • So far, I failed to successfully use Mandrills /messages/send-raw.json call. I'm not sure if I fail to create valid MIME contents, but lemme know if you make any experience with this call.

  • Also, I have no inbound-emailing set up with Mandrill. Would be great if anyone out there could test the implemented 'inbound' functionalities.

Lutung? Huh?

A monkey!!! The Javan Lutung is the name giver for this project; hat tip to MailChimp's naming scheme.

License

This library is released under the GNU Lesser General Public License http://www.gnu.org/licenses/lgpl.html.

Release 0.0.7 - Release Notes

  • Fixed custom_quota field in the submarkets API look thanks Lokesh-Github123
  • Re-enabled headers on MandrillMessageContent look
  • Re-enabled metadata on MandrillMessageInfo look
  • Catch Json parsing exceptions and throw a MandrillError with the body of the response as the message look

Release 0.0.6 - Release Notes

  • Support to specify the merge-language when using templates, look
  • Fixing endpoint URI for 'parse', look
  • Better Android compatibility, look
  • Added lables for templates, look

Thanks billoneil

Release 0.0.5 - Release Notes

  • Added messages/content.json (thanks @benfastmodel)
  • Now regarding JVM proxy parameters (thanks @joseanibl138)
  • Made commons-logging dependency optional (thanks @aldenquimby)

Release 0.0.3 - Release Notes