Getting Started

SDKs

Java SDK

Use your favorite mail provider Zupost, seamless with our Java SDK.

Null Safety

Explicit exception hierarchy with typed responses

Builder Pattern

Fluent API for constructing requests

There are many various ways of sending emails with Zupost. It can be a template, created in our no-code-editor. HTML or just markdown. No matter what you prefer, Zupost has it for you. And if you encounter issues with the documentation or the SDK, don't hesitate to open a Issue.

Installation

Start by adding the official Zupost artifact to your gradle or maven project.

Gradle

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/zupost/java-sdk")
        credentials {
            username = project.findProperty("gpr.user") as String? ?: System.getenv("GITHUB_ACTOR")
            password = project.findProperty("gpr.token") as String? ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

dependencies {
    implementation("com.zupost:zupost:0.0.0")
}

Maven

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/zupost/java-sdk</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.zupost</groupId>
        <artifactId>zupost</artifactId>
        <version>0.0.0</version>
    </dependency>
</dependencies>

Setting Up

After successfully installing Zupost to your project, you can start by creating a Zupost instance.

import com.zupost.Zupost;

Zupost zupost = new Zupost("your-api-key");

Sending Emails

You can send emails in various ways, see some usage examples:

import com.zupost.email.SendEmailOptions;
import com.zupost.email.SendEmailResponse;

// Send with HTML content
SendEmailResponse response = zupost.emails().send(
    SendEmailOptions.builder()
        .from("sender@example.com")
        .to("recipient@example.com")
        .subject("Hello World")
        .html("<h1>Hello!</h1>")
        .build()
);

System.out.println("Email sent: " + response.getId());

// Send to multiple recipients
zupost.emails().send(
    SendEmailOptions.builder()
        .from("sender@example.com")
        .to(List.of("user1@example.com", "user2@example.com"))
        .subject("Team Update")
        .markdown("# Hello Team\n\nThis is a **markdown** email.")
        .build()
);

// Send with a template
zupost.emails().send(
    SendEmailOptions.builder()
        .from("sender@example.com")
        .to("recipient@example.com")
        .subject("Welcome!")
        .templateId("welcome-template")
        .variable("name", "John")
        .html("<p>Fallback content</p>")
        .build()
);

With Attachments

You can attach files to your emails by providing them as base64-encoded strings.

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

byte[] fileBytes = Files.readAllBytes(Path.of("/path/to/invoice.pdf"));
String base64Content = Base64.getEncoder().encodeToString(fileBytes);

zupost.emails().send(
    SendEmailOptions.builder()
        .from("sender@example.com")
        .to("recipient@example.com")
        .subject("Invoice")
        .html("<p>Please find the invoice attached.</p>")
        .attachment("invoice.pdf", base64Content)
        .build()
);

Error Handling

import com.zupost.exception.ApiException;
import com.zupost.exception.ValidationException;
import com.zupost.exception.ZupostException;

try {
    zupost.emails().send(
        SendEmailOptions.builder()
            .from("sender@example.com")
            .to("recipient@example.com")
            .subject("Test")
            .html("<p>Hello</p>")
            .build()
    );
} catch (ValidationException e) {
    System.err.println("Invalid input: " + e.getMessage());
} catch (ApiException e) {
    System.err.println("API error: " + e.getStatusCode() + " - " + e.getMessage());
} catch (ZupostException e) {
    System.err.println("SDK error: " + e.getMessage());
}

Contribute on GitHub

Found an issue or want to contribute? Check out the repository for this project. We welcome contributions of all kinds!

Java SDK