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

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

## 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());
}
```