Java SDK

The HiSend Java SDK (hisend-java) provides a lightweight and modern wrapper around our REST APIs. It utilizes the native java.net.http.HttpClient introduced in Java 11, avoiding bulky legacy HTTP dependencies. For JSON serialization, it uses the incredibly fast and small Google GSON library.

By utilizing standard generic Map<String, Object> patterns, the Java SDK provides the exact same developer flexibility and speed as our dynamically typed Node.js, Python, and PHP SDKs, saving you from writing dozens of boilerplate DTO classes.

Installation

The SDK is published via JitPack. You need to add the JitPack repository and the HiSend dependency to your project.

Maven (`pom.xml`)

Add the JitPack repository and dependency:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.gethisend</groupId>
        <artifactId>java-sdk</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

Gradle (`build.gradle`)

Add the JitPack repository to your root build file at the end of repositories, and then the dependency:

allprojects {
    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

dependencies {
    implementation 'com.github.gethisend:java-sdk:1.0.0'
}

Gradle Kotlin DSL (`build.gradle.kts`)

repositories {
    mavenCentral()
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.gethisend:java-sdk:1.0.0")
}

(Note: Ensure your compiler targets Java 11 or higher).

Initialization

Import the client and initialize it using the API Key generated in your project dashboard.

import app.hisend.HisendClient;

public class App {
    public static void main(String[] args) {
        HisendClient client = new HisendClient("YOUR_API_KEY");
        
        // You can optionally pass a custom base URL 
        // HisendClient client = new HisendClient("YOUR_API_KEY", "https://api.hisend.app/v1", HttpClient.newBuilder().build());
    }
}

Resources

The SDK is divided into resources, accessible via the initialized client. For modifying API structures, we rely on standard java.util.Map<String, Object> payload objects which are automatically mapped to JSON.

Emails (`client.emails()`)

The emails resource handles sending messages and fetching sent/received history.

`send(Map<String, Object> data)`

Sends a single email.

import java.util.Map;
import java.util.HashMap;

Map<String, Object> payload = new HashMap<>();
payload.put("from", "noreply@yourdomain.com");
payload.put("to", new String[]{"user@example.com"});
payload.put("subject", "Welcome to HiSend!");
payload.put("html", "<h1>Welcome!</h1><p>We are glad to have you.</p>");

Map<String, Object> result = client.emails().send(payload);
System.out.println("Email Sent! ID: " + result.get("id"));

(Tip: Because from is a reserved word in some languages, if you happen to inject a key named "from_" into the map, the SDK automatically remaps it to "from" before transmission.)

`sendBatch(List<Map<String, Object>> data)`

Sends multiple emails in a single API request, useful for newsletters.

import java.util.List;
import java.util.Arrays;

List<Map<String, Object>> batch = Arrays.asList(
    Map.of("from", "sales@test.com", "to", new String[]{"a@test.com"}),
    Map.of("from", "sales@test.com", "to", new String[]{"b@test.com"})
);

Map<String, Object> result = client.emails().sendBatch(batch);

`list()`

Returns a list of all emails belonging to your project.

List<Map<String, Object>> emails = client.emails().list();

`get(int id)`

Retrieves the details of a specific email by its ID.

Map<String, Object> email = client.emails().get(1234);

Threads (`client.threads()`)

The threads resource handles email conversations grouping inbound and outbound replies.

`list()`

Returns all conversation threads for your project.

List<Map<String, Object>> threads = client.threads().list();

`getEmails(int id)`

Returns all individual emails that belong to a specific Thread ID, in chronological order.

List<Map<String, Object>> threadEmails = client.threads().getEmails(849);

Domains (`client.domains()`)

The domains resource manages the sender domains authorized for your project.

`list()`

Returns all domains registered to your project along with their verification statuses.

List<Map<String, Object>> domains = client.domains().list();

`get(int id)`

Retrieves the details and verification status of a specific domain by its ID.

Map<String, Object> domain = client.domains().get(101);

`add(Map<String, Object> data)`

Registers a new domain to your project.

Map<String, Object> domainPayload = Map.of("name", "newsletter.example.com");
Map<String, Object> domain = client.domains().add(domainPayload);

`verify(int id)`

Triggers a manual DNS check to verify the required records.

Map<String, Object> result = client.domains().verify(101);

`delete(int id)`

Removes a domain from your project.

client.domains().delete(101);

Routing (`client.routing()`)

The routing resource manages how inbound emails are processed.

`list(int domainId)`

Returns all inbound email routing rules configured for a specific domain.

List<Map<String, Object>> routes = client.routing().list(domainId);

`get(int domainId, int id)`

Returns the details of a specific routing rule.

Map<String, Object> route = client.routing().get(domainId, routeId);

`create(int domainId, Map<String, Object> data)`

Creates a new routing rule on a specific domain.

Map<String, Object> rulePayload = Map.of(
    "type", "specific_address",
    "email_address", "support@yourdomain.com",
    "endpoint_ids", new int[]{102, 103}
);
Map<String, Object> rule = client.routing().create(domainId, rulePayload);

`update(int domainId, int id, Map<String, Object> data)`

Updates an existing routing rule on a specific domain.

Map<String, Object> ruleUpdate = Map.of("endpoint_ids", new int[]{102});
Map<String, Object> updatedRule = client.routing().update(domainId, routeId, ruleUpdate);

`delete(int domainId, int id)`

Deletes an existing inbound routing rule.

client.routing().delete(domainId, routeId);

Error Handling

All methods in the SDK will raise an unchecked app.hisend.exceptions.HisendException if the API request is rejected (e.g., HTTP 401 Unauthorized or HTTP 400 Bad Request). The exception parses the error message safely and also grants you access to the HTTP status code.

import app.hisend.exceptions.HisendException;

try {
    Map<String, Object> result = client.emails().send(payload);
} catch (HisendException e) {
    System.err.println("Failed to send email: " + e.getMessage());
    System.err.println("HTTP Status: " + e.getStatusCode());
}

Java SDK

On this page