This is a small Java library to ease the sending of email messages using the great Mailgun service. It uses the RESTful Java client library Jersey.
What is Mailgun?
An email sending service with a REST API.
What is Jersey?
A RESTful java library. Actually, the reference implementation of JAX-RS, the standard API for RESTful web services for Java.
Add the dependency to your project:
compile 'net.sargue:mailgun:1.3.2'
<dependency>
<groupId>net.sargue</groupId>
<artifactId>mailgun</artifactId>
<version>1.3.2</version>
</dependency>
This project depends on the Jersey library (see above). The Jersey library is part of the bigger glassfish/Oracle ecosystem which apparently doesn't have top notch compatibility very high on its priority list.
Said so, you may encounter problems with dependencies as there are some libraries which are repackaged under different Maven coordinates and will leak duplicates on your classpath.
Please, see issue #1 for details and workarounds. Thanks for your understanding.
The library is pretty straighforward. You just need to remember two classes:
Configuration
: which usually is a singleton you build once and re-useMailBuilder
: the entry point to build and send emailsMailContent
: an optional helper to build HTML and text message bodys
That was three classes but the last one is optional although very useful if you want to send some simple messages in HTML.
The library is built to be used as a fluent interface, almost a DSL, so the code is quite self explanatory.
You can browse the javadocs published thanks to the great javadoc.io service.
Requires Java 7+.
Depends on Jersey 2 client.
There is not. Android is not officially supported. I have no experience on Android development so I won't be able to help much on any issue. There are a number of issues raised which indicate that the library can be used on Android but YMMV.
Anyway try it and if you find a problem please report it. I will try to help.
First of all you need to prepare a Configuration
object used by the library.
Usually you can do this once and keep the same object for all your calls. It is thread safe.
Configuration configuration = new Configuration()
.domain("somedomain.com")
.apiKey("key-xxxxxxxxxxxxxxxxxxxxxxxxx")
.from("Test account", "[email protected]");
Mail.using(configuration)
.to("[email protected]")
.subject("This is the subject")
.text("Hello world!")
.build()
.send();
Mail.using(configuration)
.to("[email protected]")
.subject("This message has an text attachment")
.text("Please find attached a file.")
.multipart()
.attachment(new File("/path/to/image.jpg"))
.build()
.send();
The classes on the package net.sargue.mailgun.content
are designed
to easily build basic HTML
messages. It's not supposed to be used for building cutting edge responsive
modern HTML messages. It's just for simple cases where you need to send a
message and you want to use some basic HTML like tables and some formatting.
Some self explanatory examples:
Mail.using(configuration)
.body()
.h1("This is a heading")
.p("And this some text")
.mail()
.to("[email protected]")
.subject("This is the subject")
.build()
.send();
Mail.using(configuration)
.body()
.h3("Monthly report")
.p("Report of the number of time travels this month")
.table()
.row("Marty", "5")
.row("Doc", "7")
.row("Einstein", "0")
.end()
.mail()
.to("[email protected]")
.subject("Monthly Delorean usage")
.build()
.send();
Of course you can keep the body content and mail building separated.
Body body = Body.builder()
.h1("This is a heading")
.p("And this some text")
.build();
Mail.using(configuration)
.to("[email protected]")
.subject("This is the subject")
.content(body)
.build()
.send();
There is also a very powerful extension mechanism which are the content converters. Check it out with some more information about the these classes in the wiki.
First published version.
- New fire and forget async send method. See
Mail.sendAsync()
. - Some notable changes on the content generation helpers. More info
in the wiki
The main code for sending simple mails hasn't changed.
TL;DR Don't use
MailBuilder
anymore, useMail.bodyBuilder()
.
Migration guide:
Where you had
MailContent mailContent = new MailContent()
[content stuff here]
.close();
MailBuilder.using(configuration)
.content(mailContent)
[mail envelope stuff here]
.build()
.send();
You can translate it to this beauty:
Mail.using(configuration)
.body()
[content stuff here]
.mail()
[mail envelope stuff here]
.build()
.send();
- New method to add inline images thanks to Lance Reid. See PR.
- New method to retrieve the body of the response. Useful to check more information in the event of errors.
- Fixed dependency: Jersey 2.25 as >2.26 targets Java EE 8 and Java 8 language level.
There is a test suite using WireMock to mock the Mailgun REST API endpoint.
The mail content test suite is a work in progress right now.
All contributions are welcome. Use the issues section to send feature requests. Pull requests are also welcome, just try to stick with the overall code style and provide some tests if possible.