# Java

## 1. Installation

Add the SDK to your project using Maven or Gradle:

<CodeTabs>
```xml title="Maven"
<dependency>
    <groupId>co.lettermint</groupId>
    <artifactId>lettermint</artifactId>
    <version>LATEST</version>
</dependency>
```

```groovy title="Gradle"
implementation 'co.lettermint:lettermint:+'
```
</CodeTabs>

## 2. Send your first email

Initialize the client with your API token:

```java
import co.lettermint.Lettermint;

Lettermint lettermint = new Lettermint("your-api-key");
```

Send your first email:

```java
SendEmailResponse response = lettermint.email()
    .from("John Doe <john@yourdomain.com>")
    .to("recipient@example.com")
    .subject("Hello from Lettermint!")
    .text("Hello! This is a test email.")
    .send();

System.out.println("Email sent with ID: " + response.getMessageId());
```

## 3. Email Features

### Basic Email

Send a simple text or HTML email:

```java
lettermint.email()
    .from("John Doe <john@yourdomain.com>")
    .to("recipient@example.com")
    .subject("Your account is ready!")
    .html("<h1>Welcome!</h1><p>Thanks for signing up.</p>")
    .text("Welcome! Thanks for signing up.")
    .send();
```

### Multiple Recipients

Send to multiple recipients using CC and BCC:

```java
lettermint.email()
    .from("John Doe <john@yourdomain.com>")
    .to("user1@example.com", "user2@example.com")
    .cc("manager@yourdomain.com")
    .bcc("archive@yourdomain.com")
    .subject("Monthly Newsletter")
    .html("<h1>This Month's Updates</h1>")
    .send();
```

### Custom Headers and Reply-To

Add custom headers and set reply-to addresses:

```java
import java.util.Map;

lettermint.email()
    .from("support@yourdomain.com")
    .to("customer@example.com")
    .replyTo("help@yourdomain.com")
    .subject("Support Ticket #12345")
    .headers(Map.of(
        "X-Priority", "1",
        "X-Ticket-ID", "12345"
    ))
    .html("<p>Your support ticket has been updated.</p>")
    .send();
```

### Metadata

Add metadata for tracking and webhook payloads:

```java
import java.util.Map;

lettermint.email()
    .from("notifications@yourdomain.com")
    .to("user@example.com")
    .subject("Order Confirmation")
    .metadata(Map.of(
        "order_id", "12345",
        "customer_id", "cust_789",
        "campaign", "order_confirmation"
    ))
    .html("<p>Your order has been confirmed.</p>")
    .send();
```

:::note
Metadata is included in webhook payloads but not added to the actual email headers. Use it for tracking and analytics purposes.
:::

### Tags

Categorize emails for filtering and analytics:

```java
lettermint.email()
    .from("alerts@yourdomain.com")
    .to("admin@example.com")
    .subject("System Alert")
    .tag("system-alerts")
    .html("<p>Critical system alert detected.</p>")
    .send();
```

:::note
One tag per message. Tags can contain letters, numbers, hyphens, underscores, and spaces (max 255 characters).
See [Tags documentation](/platform/emails/tags) for more details.
:::

### Route Selection

Direct emails to specific routes within your project:

```java
lettermint.email()
    .from("notifications@yourdomain.com")
    .to("user@example.com")
    .subject("Welcome!")
    .route("transactional")
    .html("<p>Welcome to our platform.</p>")
    .send();
```

### File Attachments

Attach files to your emails:

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

// Read file content
byte[] fileContent = Files.readAllBytes(Path.of("/path/to/document.pdf"));
String encodedContent = Base64.getEncoder().encodeToString(fileContent);

lettermint.email()
    .from("invoices@yourdomain.com")
    .to("customer@example.com")
    .subject("Your Invoice")
    .html("<p>Please find your invoice attached.</p>")
    .attach("invoice.pdf", encodedContent)
    .send();
```

## 4. Response

```java
SendEmailResponse response = lettermint.email()
    .from("John Doe <john@yourdomain.com>")
    .to("recipient@example.com")
    .subject("Test")
    .text("Hello!")
    .send();

System.out.println(response.getMessageId()); // Email ID
System.out.println(response.getStatus());    // Current status
```

## Next Steps

<CardGroup cols={2}>
    <Card title="Tags" icon="tag" href="/platform/emails/tags">
        Organize and filter emails with tags.
    </Card>
    <Card title="Tracking" icon="chart-line" href="/platform/emails/tracking/introduction">
        Track opens, clicks, and deliverability.
    </Card>
    <Card title="Webhooks" icon="webhook" href="/platform/webhooks/introduction">
        Receive real-time delivery notifications.
    </Card>
    <Card title="SMTP Alternative" icon="envelope" href="/guides/send-email-with-smtp">
        Send via SMTP instead of the API.
    </Card>
</CardGroup>

<Card title="GitHub Repository" icon="github" href="https://github.com/lettermint/lettermint-java">
    Find the complete source code, report issues, or contribute on GitHub.
</Card>