JarCastingLutung - Java Mandrill API
NOTE: this project is no longer maintained.
Lutung - a Java interface to the Mandrill API. Check out Mandrill's API [Documentation] (https://mandrillapp.com/api/docs/) 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.8</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.8 - Release Notes
-
Fixed thread safety issue with
SimpleDateFormat, create a new one each time. look thanks chrisburrell -
Added additional fields to smtp data look thanks lvogelzang
-
Make the root URL configurable look
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
- Added support for Mandrill sub accounts in MandrillApi.subaccounts.
- More support for rejects (blacklists): add and delete; also, list rejects for sub accounts.
- Added support for whitelists in MandrillApi.whitelists.
- Added support to manage sender-domains in MandrillApi.senders.
- Added support to update templates in MandrillApi.templates.
- Added support for exports in MandrillApi.exports.
- Added support for dedicated IPs and IP Pools in MandrillApi.ips.