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

# Java SDK email client

> Full reference for the Paubox Java SDK email client: building messages, sending email, tracking delivery, and error handling.

## Instantiation

After loading credentials with `ConfigurationManager.getProperties(...)`, create the service:

```java theme={null}
import com.paubox.service.EmailService;

EmailService service = new EmailService();
```

## Building a message

Messages are built by setting properties on `Message`, `Header`, and `Content` objects, then wiring them together:

```java theme={null}
import com.paubox.data.*;

Header header = new Header();
header.setFrom("sender@yourdomain.com");    // required
header.setSubject("Your results are ready"); // required
header.setReplyTo("support@yourdomain.com"); // optional

Content content = new Content();
content.setPlainText("Plain text body.");    // at least one required
content.setHtmlText("<p>HTML body.</p>");    // optional; auto base64-encoded

Message message = new Message();
message.setRecipients(new String[]{"alice@example.com"}); // required
message.setHeader(header);
message.setContent(content);
message.setCc(new String[]{"manager@example.com"});  // optional
message.setBcc(new String[]{"audit@example.com"});   // optional
message.setAllowNonTLS(false);                        // optional; default false
message.setForceSecureNotification("true");           // optional
```

### Attachments

Base64-encode the file content before setting it on the attachment:

```java theme={null}
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Base64;
import java.util.ArrayList;

byte[] fileBytes = Files.readAllBytes(Paths.get("report.pdf"));
String encoded   = Base64.getEncoder().encodeToString(fileBytes);

Attachment attachment = new Attachment();
attachment.setFileName("report.pdf");
attachment.setContentType("application/pdf");
attachment.setContent(encoded);

ArrayList<Attachment> attachments = new ArrayList<>();
attachments.add(attachment);
message.setAttachments(attachments);
```

## Send a message

```java theme={null}
SendMessageResponse response = service.sendMessage(message);
System.out.println("Tracking ID: " + response.getSourceTrackingId());
```

The `SendMessageResponse` fields:

| Method | Description |
| - | - |
| `getSourceTrackingId()` | Use to check delivery status |
| `getData()` | Raw response data |
| `getErrors()` | List of `Error` objects if the request failed |

## Check delivery status

```java theme={null}
GetEmailDispositionResponse disposition =
    service.getEmailDisposition(response.getSourceTrackingId());

for (MessageDeliveries delivery :
     disposition.getData().getMessage().getMessageDeliveries()) {
    System.out.println(
        delivery.getRecipient() + " → " +
        delivery.getStatus().getDeliveryStatus()
    );
}
```

Common `deliveryStatus` values: `delivered`, `opened`, `failed`, `pending`.

## Scheduled send

Schedule a message for future delivery, check its status, reschedule, or cancel it.

### Schedule a message

```java theme={null}
ScheduleMessageResponse response = service.scheduleMessage(message, "2025-12-25T15:00:00Z");
System.out.println("Tracking ID: " + response.getSourceTrackingId());
System.out.println("Scheduled for: " + response.getScheduledAt());
```

`scheduledAt` must be an ISO 8601 UTC datetime string in the future and within 30 days.

### Get scheduled message status

```java theme={null}
ScheduledMessageStatus status = service.getScheduledMessage(sourceTrackingId);
System.out.println("State: " + status.getState());          // "pending", "sent", "cancelled"
System.out.println("Scheduled for: " + status.getScheduledAt());
```

### Reschedule a message

```java theme={null}
RescheduleResponse response = service.rescheduleMessage(sourceTrackingId, "2025-12-26T10:00:00Z");
System.out.println("New time: " + response.getScheduledAt());
```

### Cancel a scheduled message

```java theme={null}
CancelScheduledResponse response = service.cancelScheduledMessage(sourceTrackingId);
System.out.println("State: " + response.getState());        // "cancelled"
```

## Error handling

Both `sendMessage` and `getEmailDisposition` declare `throws Exception`. Wrap calls in a try/catch block:

```java theme={null}
try {
    SendMessageResponse response = service.sendMessage(message);
    System.out.println("Sent: " + response.getSourceTrackingId());

    if (response.getErrors() != null && !response.getErrors().isEmpty()) {
        for (Error error : response.getErrors()) {
            System.err.println("Error " + error.getCode() + ": " + error.getTitle());
        }
    }
} catch (Exception e) {
    System.err.println("Send failed: " + e.getMessage());
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.