> ## 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 PHP SDK Email API client: building messages, sending email, tracking delivery, and error handling.

## Instantiation

```php theme={null}
$paubox = new Paubox\Paubox();
```

Credentials are read automatically from the `.env` file (see [Authentication](/php-sdk/authentication)). No constructor arguments are needed.

## Building a message

A message is assembled from three objects — `Header`, `Content`, and `Message` — plus optional `Attachment` objects.

### Header

```php theme={null}
$header = new Paubox\Mail\Header();
$header->setSubject("Your results are ready");   // required
$header->setFrom("sender@yourdomain.com");        // required
$header->setReplyTo("support@yourdomain.com");    // optional
```

### Content

```php theme={null}
$content = new Paubox\Mail\Content();
$content->setPlainText("Plain text body.");                       // at least one required
$content->setHtmlText("<p>HTML body.</p>");                       // optional; auto base64-encoded by SDK
```

### Message

```php theme={null}
$message = new Paubox\Mail\Message();
$message->setHeader($header);                                     // required
$message->setContent($content);                                   // required
$message->setRecipients(["alice@example.com"]);                   // required
$message->setCc(["manager@example.com"]);                         // optional
$message->setBcc(["audit@example.com"]);                          // optional
$message->setAttachments([$attachment]);                          // optional; see below
$message->setAllowNonTLS(false);                                  // optional; default false
$message->setForceSecureNotification("true");                     // optional
```

### Attachments

```php theme={null}
$attachment = new Paubox\Mail\Attachment();
$attachment->setFileName("report.pdf");
$attachment->setContentType("application/pdf");
$attachment->setContent(base64_encode(file_get_contents("/path/to/report.pdf")));

$message->setAttachments([$attachment]);
```

## Send a message

```php theme={null}
$response = $paubox->sendMessage($message);
```

The response is a `stdClass` object:

| Property           | Description                              |
| ------------------ | ---------------------------------------- |
| `sourceTrackingId` | Tracking ID for checking delivery status |
| `data`             | Raw response data                        |
| `errors`           | Array of error strings, if any           |

```php theme={null}
echo $response->sourceTrackingId;
```

## Check delivery status

```php theme={null}
$disposition = $paubox->getEmailDisposition($sourceTrackingId);
```

`$disposition->data->message->message_deliveries` is an array of per-recipient objects:

```php theme={null}
foreach ($disposition->data->message->message_deliveries as $delivery) {
    echo $delivery->recipient . " → " . $delivery->status->deliveryStatus . PHP_EOL;
}
```

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

## Error handling

Both `sendMessage` and `getEmailDisposition` throw `\Exception` on failure. Wrap calls in a try/catch block:

```php theme={null}
try {
    $response = $paubox->sendMessage($message);
    echo "Sent. Tracking ID: " . $response->sourceTrackingId . PHP_EOL;
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage() . PHP_EOL;
}
```

`sendMessage` throws if the `Header` or `Content` is null, or if the API response cannot be parsed. `getEmailDisposition` throws if the response cannot be parsed.