Email client

Full reference for the Paubox PHP SDK Email API client: building messages, sending email, tracking delivery, and error handling.

Instantiation

$paubox = new Paubox\Paubox();

Credentials are read automatically from the .env file (see 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

$header = new Paubox\Mail\Header();
$header->setSubject("Your results are ready");   // required
$header->setFrom("[e-mail]");        // required
$header->setReplyTo("[e-mail]");    // optional

Content

$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

$message = new Paubox\Mail\Message();
$message->setHeader($header);                                     // required
$message->setContent($content);                                   // required
$message->setRecipients(["[e-mail]"]);                   // required
$message->setCc(["[e-mail]"]);                         // optional
$message->setBcc(["[e-mail]"]);                          // optional
$message->setAttachments([$attachment]);                          // optional; see below
$message->setAllowNonTLS(false);                                  // optional; default false
$message->setForceSecureNotification("true");                     // optional

Attachments

$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

$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

echo $response->sourceTrackingId;

Check delivery status

$disposition = $paubox->getEmailDisposition($sourceTrackingId);

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

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:

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.