# 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](https://github.com/mailjet/mailjet-apiv3-java).

Current release: **6.0.0**

## Compatibility

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

## Installation

```xml
<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:

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

```java
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](#sms-api).

## Send your first email

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

```java
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:

```java
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:

```java
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](https://square.github.io/okhttp/) 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`:

```java
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`](https://github.com/mailjet/mailjet-apiv3-java/blob/master/src/main/java/com/mailjet/client/resource).

### POST — create an object

```java
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`:

```java
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

```java
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.

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

MailjetResponse response = client.get(request);
```

### GET — a single object

```java
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.

```java
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.

```java
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](https://app.mailjet.com/sms) of your account:

```java
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](https://github.com/mailjet/mailjet-apiv3-java/blob/master/src/test/java/com/mailjet/client/SendSmsIT.java).

## 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](https://github.com/fouad-j/aws-lambda-java-jetmail)


## 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](https://github.com/mailjet/mailjet-apiv3-java). Documentation improvements belong in the [API documentation repo](https://github.com/mailjet/api-documentation).