README

BulkTo PHP Client is a modern, Composer-installable library for integrating your PHP applications with the BulkTo transactional & bulk email API.

• Send transactional (one-to-one) or bulk (multi-recipient) mail
• Get delivery status
• Retrieve user DKIM keys
• Handles attachments, unsubscribe, custom bounce, and more
• Robust input validation and exception handling
• Designed for simple integration into any PHP project

Installation

composer require bulkto/bulkto-client

Requires PHP 8.0+ and GuzzleHttp.

Usage

Basic Initialization

use BulkTo\Client;

$jwt = 'your-jwt-token-here';
$bulkto = new Client($jwt);
// Optionally: $bulkto = new Client($jwt, 'https://api.bulkto.net');

Sending a Transactional Email

$bulkto->setMessageType('transaction')
    ->setFrom('sender@example.com', 'Sender Name')
    ->addTo('recipient@example.com') // or ->addTo('Recipient Name', 'recipient@example.com')
    ->setSubject('Hello')
    ->setMessage('<p>Welcome to BulkTo!</p>')
    ->addAttachment('welcome.pdf', 'application/pdf', $base64data)
    ->setUnsubscribe(['recipient@example.com', 'https://example.com/unsub'])
    ->setBounceAddr('bounces@example.com');

$response = $bulkto->send();
// $response contains API response data (e.g. status, message ID)

You should store the message-id provided back to you from the send call for looking up delivery status later

Sending a Bulk Email

$bulkto->setMessageType('bulk')
    ->setFrom('no-reply@example.com', 'Acme Team')
    ->addRecipient('Alice', 'alice@example.com')
    ->addRecipient('Bob', 'bob@example.com')
    ->setSubject('Monthly Update')
    ->setMessage('<h1>Hi!</h1><p>Our newsletter...</p>')
    ->setListId('list-42')
    ->setUnsubscribe(['unsubscribe@example.com', 'https://example.com/unsub'])
    ->addAttachment('promo.jpg', 'image/jpeg', $base64data)
    ->setBounceAddr('bounce@example.com');

$response = $bulkto->send();

Status Lookup

$status = $bulkto->lookupStatus('message-id-xyz'); // returns delivery status info
$statusByRecipient = $bulkto->lookupStatus('message-id-xyz', 'bob@example.com');

DKIM Lookup

$dkim = $bulkto->getDkim('user-uuid'); // returns DKIM public key info

Unsubscribe Handling

• You must provide a List-Unsubscribe value for bulk mail.

• Acceptable:

  • A single email (user@example.com) — will be sent as mailto:user@example.com
  • A single URL (https://example.com/unsub)
  • Both as an array (['user@example.com', 'https://example.com/unsub'])
• Not allowed: two emails, or two URLs.

Example:

// All are valid:
$bulkto->setUnsubscribe('user@example.com');
$bulkto->setUnsubscribe('https://example.com/unsub');
$bulkto->setUnsubscribe(['user@example.com', 'https://example.com/unsub']);

Error Handling

All exceptions extend BulkTo\Exception\BulkToException. You can catch specific error types:

use BulkTo\Exception\BulkToValidationException;
use BulkTo\Exception\BulkToApiException;

try {
    $bulkto->setFrom('bad-email');
} catch (BulkToValidationException $e) {
    // Input error
}

try {
    $bulkto->send();
} catch (BulkToApiException $e) {
    // API/server error
} catch (BulkToValidationException $e) {
    // Input error (e.g. missing field)
} catch (BulkToException $e) {
    // All other errors
}

Testing

Unit tests provided (see tests/). Run with:

./vendor/bin/phpunit tests

API Methods

Contributing

Pull requests, bug reports, and suggestions welcome! Please open issues or PRs via your Portal.

(https://git.bandabi.ca/bulkto/php-client.git).

License

MIT

BulkTo is a trademark of Aim 4 The Cloud Inc