Email client

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

Instantiation

my $service = Paubox_Email_SDK->new();

Credentials are read automatically from config.cfg (see Authentication). The constructor dies if API_KEY or API_USERNAME is missing.

Building a message

Messages are created with a single constructor call using named parameters:

my $msg = Paubox_Email_SDK::Message->new(
    'from'                    => '[e-mail]',  # required
    'to'                      => ['[e-mail]'],     # required; arrayref
    'subject'                 => 'Your results are ready',  # required
    'text_content'            => 'Plain text body.',        # at least one required
    'html_content'            => '<p>HTML body.</p>',       # optional; auto base64-encoded
    'replyTo'                 => '[e-mail]',  # optional
    'cc'                      => ['[e-mail]'],   # optional; arrayref
    'bcc'                     => ['[e-mail]'],     # optional; arrayref
    'allowNonTLS'             => 0,                         # optional; default 0
    'forceSecureNotification' => 'true',                    # optional; "true"/"false"
    'attachments'             => [$attachment],             # optional; arrayref of hashrefs
);

Attachments

Each attachment is a hashref with three keys. Use MIME::Base64 to encode the file content:

use MIME::Base64;
use String::Util qw(trim);

my $attachment = {
    fileName    => 'report.pdf',
    contentType => 'application/pdf',
    content     => trim(encode_base64(do { local $/; open my $fh, '<:raw', 'report.pdf' or die $!; <$fh> })),
};

my $msg = Paubox_Email_SDK::Message->new(
    'from'        => '[e-mail]',
    'to'          => ['[e-mail]'],
    'subject'     => 'Report attached',
    'text_content'=> 'See attachment.',
    'attachments' => [$attachment],
);

String::Util::trim removes the trailing newline that encode_base64 appends.

Send a message

my $response = $service->sendMessage($msg);

The response is a raw JSON string. Decode it to access fields:

use JSON;
my $json = decode_json($response);
print "Tracking ID: " . $json->{sourceTrackingId} . "\n";

Check delivery status

my $disposition = $service->getEmailDisposition($sourceTrackingId);
my $json = decode_json($disposition);

for my $delivery (@{ $json->{data}{message}{message_deliveries} }) {
    print $delivery->{recipient} . " -> " . $delivery->{status}{deliveryStatus} . "\n";
}

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

Error handling

Both sendMessage and getEmailDisposition use TryCatch internally and die on API errors. Wrap calls in an eval block to catch failures:

eval {
    my $response = $service->sendMessage($msg);
    print "Sent: $response\n";
};
if ($@) {
    print "Error: $@\n";
}