Repository files navigation

Since I created this library Mailgun has released anofficial Java library. Please check it.You might want to use it instead of this one, as it has more features and ismaintained by the Mailgun team. I haven't used it myself.

This is a small Java library to ease the sending of email messages using thegreatMailgun service. It uses the RESTful Javaclient libraryJersey.

An email sending service with a REST API.

A RESTful java library. Actually, the reference implementation ofJAX-RS, the standard API for RESTful webservices for Java.

Version 2.x.x usesjakarta.* package naming.

If you need the legacyjavax.* package naming, please stick with 1.x.x versions.

Add the dependency to your project:

implementation 'net.sargue:mailgun:2.0.0'

<dependency>    <groupId>net.sargue</groupId>    <artifactId>mailgun</artifactId>    <version>2.0.0</version></dependency>

This project depends on the Jersey library (see above). The Jersey libraryis part of the biggerglassfish/Oracle ecosystem which apparentlydoesn't have top-notch compatibility very high on its priority list.

Said so, you may encounter problems with dependencies as there are somelibraries which are repackaged under different Maven coordinates and willleak duplicates on your classpath.

Please, seeissue #1 for detailsand 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-use
• Mail: the entry point to build and send emails
• MailContent: an optional helper to build HTML and text message bodys

That were three classes but the last one is optional although very usefulif 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 codeis quite self-explanatory.

You canbrowse the javadocspublished thanks to the great javadoc.io service.

The runtime requirement is Java 8 or higher.

Depends onJersey 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 anumber of issues raised which indicate that the librarycan be used on Android but YMMV.

The main issue about using this library on android is the repackaging of some packages done by Jersey, likejavax.inject. If using gradle you could try to add this:

configurations {    all*.excludegroup:'org.glassfish.hk2.external',module:'javax.inject'}

Anyway try it and if you find a problem please report it. I will try to help.

First, you need to prepare aConfiguration object used by the library.

Usually you can do this once and keep the same object for all your calls. Itis thread safe.

Configurationconfiguration =newConfiguration()    .domain("somedomain.com")    .apiKey("key-xxxxxxxxxxxxxxxxxxxxxxxxx")    .from("Test account","postmaster@somedomain.com");

The default configuration por the API base URL is the US endpoint. If you areusinga different endpoint you should set the base URL manually on theconfiguration object.

Example to use the EU (European) endpoint:

Configurationconfiguration =newConfiguration()    .domain("somedomain.com")    .apiUrl("https://api.eu.mailgun.net/v3")    .apiKey("key-xxxxxxxxxxxxxxxxxxxxxxxxx")    .from("Test account","postmaster@somedomain.com");

Mail.using(configuration)    .to("marty@mcfly.com")    .subject("This is the subject")    .text("Hello world!")    .build()    .send();

Mail.using(configuration)    .to("marty@mcfly.com")    .subject("This message has an text attachment")    .text("Please find attached a file.")    .multipart()    .attachment(newFile("/path/to/image.jpg"))    .build()    .send();

Some fields (more or less the ones that make sense) can be repeated.Liketo() to send to multiple recipients,attachment() to includemore than one attachment and so on.

Mail.using(configuration)    .to("marty@mcfly.com")    .to("george@mcfly.com")    .cc("lorraine@mcfly.com")    .cc("dave@mcfly.com")    .subject("This is the subject")    .text("Hello world!")    .build()    .send();

Mail.using(configuration)    .to("marty@mcfly.com")    .subject("This message has an text attachment")    .text("Please find attached a file.")    .multipart()    .attachment(newFile("/path/to/image.jpg"))    .attachment(newFile("/path/to/report.pdf"))    .build()    .send();

Mail.using(configuration)    .to("marty@mcfly.com")    .subject("Activate your account")    .template("account_activation")    .parameter("v:name","Doc Brown")    .build()    .send();

The classes on the packagenet.sargue.mailgun.content are designedto easily build basic HTMLmessages. It's not supposed to be used for building cutting edge responsivemodern HTML messages. It's just for simple cases where you need to send amessage with 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("marty@mcfly.com")    .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("marty@mcfly.com")    .subject("Monthly Delorean usage")    .build()    .send();

Of course, you can keep the body content and mail building separated.

Bodybody =Body.builder()                .h1("This is a heading")                .p("And this some text")                .build();Mail.using(configuration)    .to("marty@mcfly.com")    .subject("This is the subject")    .content(body)    .build()    .send();

There is also a very powerful extension mechanism which are thecontentconverters. Check it out with some more information about the theseclassesin the wiki.

The changelog is in aseparate page.

There is a test suite usingWireMock to mock the MailgunREST 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 styleand provide some tests if possible.