> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Send transactional emails from Java with the official Lettr SDK, featuring type-safe builders and Java 11+ support.

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](https://cursor.com/link/prompt?text=Help%20me%20add%20a%20Lettr%20sending%20example%20for%20Java%20using%20com.lettr%3Alettr-java%2C%20or%20migrate%20my%20current%20Java%20sending%20solution%20to%20Lettr%20using%20these%20docs%3A%20https%3A%2F%2Fdocs.lettr.com%2Fquickstart%2Fjava%2Fquickstart)

## 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

<Note>
  If you prefer not to use the SDK, you can also send emails via [SMTP](/quickstart/smtp/introduction) or make direct [HTTP API](/api-reference/emails/send-email) calls.
</Note>

## Prerequisites

Before you begin, make sure you have:

<CardGroup cols={2}>
  <Card title="API Key" icon="key" href="https://app.lettr.com/api-keys">
    Create an API key in the Lettr dashboard
  </Card>

  <Card title="Verified Domain" icon="globe" href="/learn/domains/sending-domains">
    Add and verify your sending domain
  </Card>
</CardGroup>

You'll also need:

* **Java 11 or later** installed
* **Maven** or **Gradle** for dependency management
* A verified sending domain in your [Lettr dashboard](https://app.lettr.com/domains)

## Quick Setup

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

<Steps>
  <Step title="Add the dependency">
    Add the Lettr SDK to your project using Maven or Gradle:

    <CodeGroup>
      ```xml Maven theme={null}
      <dependency>
          <groupId>com.lettr</groupId>
          <artifactId>lettr-java</artifactId>
          <version>1.1.0</version>
      </dependency>
      ```

      ```gradle Gradle theme={null}
      implementation 'com.lettr:lettr-java:1.1.0'
      ```

      ```gradle Gradle (Kotlin DSL) theme={null}
      implementation("com.lettr:lettr-java:1.1.0")
      ```
    </CodeGroup>

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

  <Step title="Create a client">
    ```java theme={null}
    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.");
        }
    }
    ```

    <Tip>
      Store your API key in environment variables, never hardcode it. API keys use the `lttr_` prefix followed by 64 hexadecimal characters.
    </Tip>
  </Step>

  <Step title="Send your first email">
    ```java theme={null}
    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.
  </Step>
</Steps>

<Warning>
  The sender domain must be verified in your [Lettr dashboard](https://app.lettr.com/domains) before you can send emails. Sending from an unverified domain returns a validation error.
</Warning>

## Configuration

### Environment Variables

Read your API key from an environment variable:

```java theme={null}
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:

```properties theme={null}
# application.properties
lettr.api.key=lttr_your_api_key_here
```

```java theme={null}
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);
    }
}
```

<Tip>
  Add `application.properties` to your `.gitignore` file to prevent accidentally committing your API key to version control.
</Tip>

### Custom HTTP Client

Use a custom HTTP client with custom timeouts:

```java theme={null}
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:

```java theme={null}
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:

```java theme={null}
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:

```java theme={null}
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:

```java theme={null}
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);
```

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

## Explore the SDK

Beyond sending, the SDK manages every Lettr resource:

<CardGroup cols={2}>
  <Card title="Templates" icon="file-code" href="/quickstart/java/templates">
    Manage Lettr templates and merge tags
  </Card>

  <Card title="Domains" icon="globe" href="/quickstart/java/domains">
    Add, verify, and manage sending domains
  </Card>

  <Card title="Webhooks" icon="bell" href="/quickstart/java/webhooks">
    Manage webhook endpoints for delivery and engagement events
  </Card>

  <Card title="Audience" icon="users" href="/quickstart/java/audience">
    Lists, contacts, topics, properties, and segments
  </Card>

  <Card title="Campaigns" icon="paper-plane" href="/quickstart/java/campaigns">
    List, send, and schedule campaigns
  </Card>
</CardGroup>

## What's Next

<CardGroup cols={2}>
  <Card title="Advanced Features" icon="rocket" href="/quickstart/java/advanced">
    Attachments, templates, batch sending, and more
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete API documentation
  </Card>

  <Card title="Best Practices" icon="shield-check" href="/knowledge-base/best-practices/deliverability">
    Email deliverability tips
  </Card>
</CardGroup>