Java SDK

The official Java wrapper for the Mailjet API is published to Maven Central as com.mailjet:mailjet-client and developed at mailjet/mailjet-apiv3-java.

Current release: 6.0.0

Compatibility

The 6.x line runs on Java 11 or higher.

Installation

<dependencies>
    <dependency>
        <groupId>com.mailjet</groupId>
        <artifactId>mailjet-client</artifactId>
        <version>6.0.0</version>
    </dependency>
</dependencies>

Authentication

The Email API authenticates with your API key and secret:

export MJ_APIKEY_PUBLIC='your API key'
export MJ_APIKEY_PRIVATE='your API secret'

ClientOptions options = ClientOptions.builder()
        .apiKey(System.getenv("MJ_APIKEY_PUBLIC"))
        .apiSecretKey(System.getenv("MJ_APIKEY_PRIVATE"))
        .build();

MailjetClient client = new MailjetClient(options);

Tip: register MailjetClient as a singleton and reuse it across sends. Creating a client per message wastes connections and threads.

The SMS API authenticates with a bearer token instead — see SMS API.

Send your first email

The transactional email builder is the recommended path — it produces a typed message and handles serialisation for you.

TransactionalEmail message = TransactionalEmail
        .builder()
        .to(new SendContact("passenger@example.com", "Passenger 1"))
        .from(new SendContact("pilot@example.com", "Mailjet Pilot"))
        .subject("Your email flight plan!")
        .htmlPart("<h1>This is the HTML content of the mail</h1>")
        .trackOpens(TrackOpens.ENABLED)
        .attachment(Attachment.fromFile(attachmentPath))
        .header("test-header-key", "test-value")
        .customID("custom-id-value")
        .build();

SendEmailsRequest request = SendEmailsRequest
        .builder()
        .message(message) // up to 50 messages per request
        .build();

SendEmailsResponse response = request.sendWith(client);

Attachments can also be created from an InputStream, which is useful when the file never touches disk.

Using the JSON object syntax

The older, untyped style is still supported and maps one-to-one onto the Send API v3.1 payload:

package com.my.project;

import com.mailjet.client.ClientOptions;
import com.mailjet.client.MailjetClient;
import com.mailjet.client.MailjetRequest;
import com.mailjet.client.MailjetResponse;
import com.mailjet.client.errors.MailjetException;
import com.mailjet.client.resource.Emailv31;
import org.json.JSONArray;
import org.json.JSONObject;

public class MyClass {
    public static void main(String[] args) throws MailjetException {
        ClientOptions options = ClientOptions.builder()
                .apiKey(System.getenv("MJ_APIKEY_PUBLIC"))
                .apiSecretKey(System.getenv("MJ_APIKEY_PRIVATE"))
                .build();

        MailjetClient client = new MailjetClient(options);

        MailjetRequest request = new MailjetRequest(Emailv31.resource)
                .property(Emailv31.MESSAGES, new JSONArray()
                        .put(new JSONObject()
                                .put(Emailv31.Message.FROM, new JSONObject()
                                        .put("Email", "pilot@example.com")
                                        .put("Name", "Mailjet Pilot"))
                                .put(Emailv31.Message.TO, new JSONArray()
                                        .put(new JSONObject()
                                                .put("Email", "passenger@example.com")
                                                .put("Name", "Passenger 1")))
                                .put(Emailv31.Message.SUBJECT, "My first Mailjet Email!")
                                .put(Emailv31.Message.TEXTPART, "Greetings from Mailjet!")
                                .put(Emailv31.Message.HTMLPART, "<h3>Dear passenger 1, welcome to Mailjet!</h3>")));

        MailjetResponse response = client.post(request);

        System.out.println(response.getStatus());
        System.out.println(response.getData());
    }
}

Client and call configuration

Timeouts and request logging

The client is built on OkHttp. Pass a pre-configured OkHttpClient to control timeouts, logging, interceptors and connection pooling:

HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
logging.setLevel(Level.BASIC);

OkHttpClient customHttpClient = new OkHttpClient.Builder()
        .connectTimeout(60, TimeUnit.SECONDS)
        .readTimeout(60, TimeUnit.SECONDS)
        .writeTimeout(60, TimeUnit.SECONDS)
        .addInterceptor(logging)
        .build();

ClientOptions options = ClientOptions.builder()
        .apiKey(System.getenv("MJ_APIKEY_PUBLIC"))
        .apiSecretKey(System.getenv("MJ_APIKEY_PRIVATE"))
        .okHttpClient(customHttpClient)
        .build();

See the OkHttp documentation for the full set of options.

API versioning

Version	Scope
`v3`	Email API
`v3.1`	Send API v3.1 (latest send version)
`v4`	SMS API

You do not need to configure this. Since 5.0.0 the client derives the required version from the resource itself.

Base URL

The default base domain is api.mailjet.com. Override it in ClientOptions:

ClientOptions options = ClientOptions.builder()
        .baseUrl("https://api.us.mailjet.com")
        .apiKey(System.getenv("MJ_APIKEY_PUBLIC"))
        .apiSecretKey(System.getenv("MJ_APIKEY_PRIVATE"))
        .build();

MailjetClient client = new MailjetClient(options);

Accounts on Mailjet's US architecture must set https://api.us.mailjet.com.

HTTP proxy

The proxy is configured through the standard JVM system properties:

-Dhttp.proxyHost=
-Dhttp.proxyPort=

-Dhttps.proxyHost=
-Dhttps.proxyPort=

If you call other endpoints through java.net.HttpURLConnection that should bypass the proxy:

-Dhttp.nonProxyHosts=<hosts to exclude>

Request examples

Requests are MailjetRequest objects built from a resource constant, an optional ID, properties and filters. The full list of resources is in src/main/java/com/mailjet/client/resource.

POST — create an object

MailjetRequest request = new MailjetRequest(Contact.resource)
        .property(Contact.EMAIL, "passenger@example.com");

MailjetResponse response = client.post(request);

System.out.println(response.getStatus());
System.out.println(response.getData());

POST — endpoints with an action

Action endpoints have their own resource object. /contact/{id}/managecontactslists maps to ContactManagecontactslists:

MailjetRequest request = new MailjetRequest(ContactManagecontactslists.resource, contactId)
        .property(ContactManagecontactslists.CONTACTSLISTS, new JSONArray()
                .put(new JSONObject()
                        .put("ListID", listId1)
                        .put("Action", "addnoforce"))
                .put(new JSONObject()
                        .put("ListID", listId2)
                        .put("Action", "addforce")));

MailjetResponse response = client.post(request);

GET — all objects

MailjetRequest request = new MailjetRequest(Contact.resource);
MailjetResponse response = client.get(request);

GET — with filtering and sorting

Add filters with .filter(). Sorting takes a property name and an order (ASC or DESC) separated by a space. Neither Sort nor descending order is available for every property.

MailjetRequest request = new MailjetRequest(Contact.resource)
        .filter(Contact.ISEXCLUDEDFROMCAMPAIGNS, "false")
        .filter("Sort", "CreatedAt DESC");

MailjetResponse response = client.get(request);

GET — a single object

MailjetRequest request = new MailjetRequest(Contact.resource, contactId);
MailjetResponse response = client.get(request);

PUT — update an object

A PUT in the Mailjet API behaves like a PATCH: only the properties you send are updated, everything else is left untouched, and non-mandatory properties can be omitted.

MailjetRequest request = new MailjetRequest(Contactdata.resource, contactId)
        .property(Contactdata.DATA, new JSONArray()
                .put(new JSONObject()
                        .put("Name", "Age")
                        .put("Value", "30"))
                .put(new JSONObject()
                        .put("Name", "Country")
                        .put("Value", "US")));

MailjetResponse response = client.put(request);

DELETE — remove an object

A successful DELETE returns 204 No Content with no response body.

MailjetRequest request = new MailjetRequest(Template.resource, templateId);
MailjetResponse response = client.delete(request);

SMS API

SMS endpoints authenticate with a bearer token generated in the SMS section of your account:

MailjetClient client = new MailjetClient(ClientOptions
        .builder()
        .bearerAccessToken(System.getenv("MJ_APITOKEN"))
        .build());

MailjetRequest request = new MailjetRequest(SmsSend.resource)
        .property(SmsSend.FROM, "MJPilot")
        .property(SmsSend.TO, "+4915200000000")
        .property(SmsSend.TEXT, "Have a nice SMS flight with Mailjet!");

MailjetResponse response = client.post(request);

More usage patterns are covered by the repository's integration tests.

Release notes

Version	Changes
6.0.0	Moves to Java 11; adds and updates unit tests
5.2.6	Fixes vulnerabilities; moves to Java 11
5.2.4	Adds file attachments to requests; fixes CSV upload through the Data API
5.2.0	Adds async methods, an automatic module name, and attachments from `InputStream`
5.1.1	Fixes extra quotes when serialising string variables and headers in `TransactionalEmailBuilder`
5.1.0	Adds the transactional email builder; downgrades OkHttp to 3.12 for Spring Boot compatibility
5.0.0	Migrates to OkHttp; removes `ApiVersion` from client config (resolved per resource); adds the `ClientOptions` builder

Other examples

AWS Lambda integration

Contribute

The wrapper is open source. Fork the repository, branch, implement your fix or feature, add documentation and specs, and open a pull request at mailjet/mailjet-apiv3-java. Documentation improvements belong in the API documentation repo.