Getting Started

Send transactional emails from your Java applications using the official Lettr Java SDK. The SDK provides a type-safe, builder-pattern interface for the Lettr API with comprehensive error handling and Java 11+ support. The lettr-java package gives you an idiomatic Java client that works with any Java application — Spring Boot, Jakarta EE, Android, or standalone applications. It follows Java conventions and integrates seamlessly with your existing codebase. Using Cursor? Jump straight in using this prompt

Why Use the Java SDK?

Rather than making raw HTTP requests, the SDK provides:

Type-safe API — Full type safety with builder patterns and immutable objects
Fluent builders — Chainable methods for constructing complex emails
Exception handling — Typed exceptions for different error scenarios
Java 11+ support — Works with modern Java versions and HTTP clients
Zero runtime dependencies — Minimal footprint with only HTTP client requirements

If you prefer not to use the SDK, you can also send emails via SMTP or make direct HTTP API calls.

Prerequisites

Before you begin, make sure you have:

API Key

Create an API key in the Lettr dashboard

Verified Domain

Add and verify your sending domain

You’ll also need:

Java 11 or later installed
Maven or Gradle for dependency management
A verified sending domain in your Lettr dashboard

Quick Setup

Get started in three quick steps: add the dependency, create a client, and send.

Add the dependency

Add the Lettr SDK to your project using Maven or Gradle:

<dependency>
    <groupId>com.lettr</groupId>
    <artifactId>lettr-java</artifactId>
    <version>1.1.0</version>
</dependency>

implementation 'com.lettr:lettr-java:1.1.0'

implementation("com.lettr:lettr-java:1.1.0")

The SDK requires Java 11+ and uses the Java HTTP Client (java.net.http) for making requests.

Create a client

import com.lettr.Lettr;

public class Main {
    public static void main(String[] args) {
        String apiKey = System.getenv("LETTR_API_KEY");
        Lettr lettr = new Lettr(apiKey);

        System.out.println("Lettr client initialized.");
    }
}

Store your API key in environment variables, never hardcode it. API keys use the lttr_ prefix followed by 64 hexadecimal characters.

Send your first email

import com.lettr.services.emails.model.CreateEmailOptions;
import com.lettr.services.emails.model.CreateEmailResponse;

CreateEmailOptions email = CreateEmailOptions.builder()
    .from("sender@yourdomain.com")
    .to("recipient@example.com")
    .subject("Hello from Lettr")
    .html("<h1>Hello!</h1><p>This is a test email.</p>")
    .build();

try {
    CreateEmailResponse response = lettr.emails().send(email);
    System.out.println("Email sent! Request ID: " + response.getRequestId());
    System.out.println("Accepted: " + response.getAccepted());
} catch (Exception e) {
    e.printStackTrace();
}

The response includes a requestId for tracking and the number of accepted recipients.

The sender domain must be verified in your Lettr dashboard before you can send emails. Sending from an unverified domain returns a validation error.

Configuration

Environment Variables

Read your API key from an environment variable:

public class Main {
    public static void main(String[] args) {
        String apiKey = System.getenv("LETTR_API_KEY");
        if (apiKey == null || apiKey.isEmpty()) {
            throw new IllegalStateException("LETTR_API_KEY environment variable is required");
        }

        Lettr lettr = new Lettr(apiKey);
    }
}

Using Properties Files

Load configuration from a properties file:

# application.properties
lettr.api.key=lttr_your_api_key_here

import java.io.FileInputStream;
import java.io.IOException;
import java.util.Properties;

public class Main {
    public static void main(String[] args) throws IOException {
        Properties props = new Properties();
        props.load(new FileInputStream("application.properties"));

        String apiKey = props.getProperty("lettr.api.key");
        Lettr lettr = new Lettr(apiKey);
    }
}

Add application.properties to your .gitignore file to prevent accidentally committing your API key to version control.

Custom HTTP Client

Use a custom HTTP client with custom timeouts:

import java.net.http.HttpClient;
import java.time.Duration;

HttpClient httpClient = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(30))
    .build();

Lettr lettr = new Lettr("your-api-key", httpClient);

Sending Emails

Basic HTML Email

Send a simple HTML email:

CreateEmailOptions email = CreateEmailOptions.builder()
    .from("notifications@yourdomain.com")
    .to("user@example.com")
    .subject("Welcome to our service")
    .html("<h1>Welcome!</h1><p>Thanks for signing up.</p>")
    .build();

try {
    CreateEmailResponse response = lettr.emails().send(email);
    System.out.println("Email sent successfully (Request ID: " + response.getRequestId() + ")");
} catch (Exception e) {
    System.err.println("Failed to send email: " + e.getMessage());
}

With Display Name

Add a friendly display name to the sender address:

CreateEmailOptions email = CreateEmailOptions.builder()
    .from("notifications@yourdomain.com")
    .fromName("Acme Corp")
    .to("user@example.com")
    .subject("Welcome to Acme")
    .html("<h1>Hello!</h1>")
    .build();

lettr.emails().send(email);

Plain Text Email

Send a plain text email without HTML:

CreateEmailOptions email = CreateEmailOptions.builder()
    .from("notifications@yourdomain.com")
    .to("user@example.com")
    .subject("Plain text email")
    .text("This is a plain text email.\n\nIt has no HTML formatting.")
    .build();

lettr.emails().send(email);

Multipart Emails (HTML + Text)

Send both HTML and plain text versions for maximum compatibility:

CreateEmailOptions email = CreateEmailOptions.builder()
    .from("notifications@yourdomain.com")
    .to("user@example.com")
    .subject("Multipart email")
    .html("<h1>Hello!</h1><p>This is the HTML version.</p>")
    .text("Hello!\n\nThis is the plain text version.")
    .build();

lettr.emails().send(email);

Providing both HTML and plain text ensures your emails are readable in all email clients, including text-only clients and accessibility tools.

Explore the SDK

Beyond sending, the SDK manages every Lettr resource:

Templates

Manage Lettr templates and merge tags

Domains

Add, verify, and manage sending domains

Webhooks

Manage webhook endpoints for delivery and engagement events

Audience

Lists, contacts, topics, properties, and segments

Campaigns

List, send, and schedule campaigns

What’s Next

Advanced Features

Attachments, templates, batch sending, and more

API Reference

Complete API documentation

Best Practices

Email deliverability tips

​Why Use the Java SDK?

​Prerequisites

API Key

Verified Domain

​Quick Setup

​Configuration

​Environment Variables

​Using Properties Files

​Custom HTTP Client

​Sending Emails

​Basic HTML Email

​With Display Name

​Plain Text Email

​Multipart Emails (HTML + Text)

​Explore the SDK

Templates

Domains

Webhooks

Audience

Campaigns

​What’s Next

Advanced Features

API Reference

Best Practices

Why Use the Java SDK?

Prerequisites

Quick Setup

Configuration

Environment Variables

Using Properties Files

Custom HTTP Client

Sending Emails

Basic HTML Email

With Display Name

Plain Text Email

Multipart Emails (HTML + Text)

Explore the SDK

What’s Next