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

Method	Description
setMessageType	Set message type: `transaction` or `bulk`
setFrom	Set sender email and name
addTo	Add transactional recipient (name optional)
addRecipient	Add bulk recipient (name, email)
setSubject	Set subject
setMessage	Set message body (HTML or text)
addAttachment	Add base64-encoded attachment
setUnsubscribe	Set unsubscribe (email, URL, or both)
setListId	Set List-ID (bulk only)
setBounceAddr	Set bounce address (optional)
addCc	Add CC (transactional only)
send	Send the composed message
lookupStatus	Get status of a sent message
getDkim	Retrieve user DKIM public key

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

bulkto / bulkto-client

Maintainers

Package info

Statistics

Security