@orboto/mail - PHP SDK

Official PHP SDK for the Orboto Mail Service. Drop-in transactional-mail client with auto-quota-tracking, retry-with-backoff, quota lifecycle events, typed DTOs, and a Laravel Service-Provider out of the box. EU-hosted, GDPR-compliant.

Same API surface as the TypeScript SDK @orboto/mail - release versions stay in lockstep.

Install

composer require orboto/mail

Requires PHP 8.2+ and any PSR-18 HTTP client (Guzzle is auto-discovered if present; see HTTP client below if you want to plug in a different one).

Quick start

useOrboto\Mail\OrbotoMail;
$mail = newOrbotoMail(['apiKey' => $_ENV['OMS_API_KEY']]);
$result = $mail->send([
'from' => 'noreply@acme.orbo.to',
'to' => 'user@example.com',
'subject' => 'Welcome',
'html' => '<h1>Welcome!</h1>',
]);
echo$result->messageId; // server-issued message idecho$result->status; // 'queued' at success-timeecho$result->remainingQuota->percentUsed; // 0.0 .. 1.x

Get an API key at account.orboto.io/mail/api-keys.

Send with CC + BCC

$result = $mail->send([
'from' => 'support@customer.de',
'to' => 'primary@example.com',
'cc' => ['cc1@example.com', 'cc2@example.com'], // visible to all (max 50)'bcc' => ['silent@example.com'], // envelope-only (max 50)'subject' => 'Quarterly report',
'html' => '<p>See attached.</p>',
]);

Max 50 entries each. cc recipients show in the recipient's headers; bcc recipients receive the mail but never appear in any header (envelope-only per RFC 2822). One quota decrement per call regardless of recipient count.

Send with attachments

$result = $mail->send([
'from' => 'noreply@acme.orbo.to',
'to' => 'user@example.com',
'subject' => 'Your invoice',
'html' => '<p>Find your invoice attached.</p>',
'attachments' => [
[
'filename' => 'invoice-2026-06.pdf',
'content' => base64_encode(file_get_contents('/tmp/invoice.pdf')),
'contentType' => 'application/pdf',
],
],
]);

Up to 20 attachments per send; total decoded size capped at 30 MB. Pass an optional contentId to reference an attachment inline from your HTML (<img src="cid:logo-1">).

Send a batch

$batch = $mail->sendBatch([
'messages' => [
['from' => 'a@x.com', 'to' => 'u1@example.com', 'subject' => 'Hi 1', 'text' => 'Hello 1'],
['from' => 'a@x.com', 'to' => 'u2@example.com', 'subject' => 'Hi 2', 'text' => 'Hello 2'],
],
]);
foreach ($batch->resultsas$item) {
if (!$item->ok) {
error_log("Send #{$item->index} failed: {$item->reason}");
}
}
echo"{$batch->summary->queued} queued, {$batch->summary->suppressed} suppressed.";

Capped at 100 messages per call. Per-item processing - the call as a whole always returns 200; inspect $batch->summary and per-item ok flags to decide whether to retry indices.

Templates

$tpl = $mail->templates->create([
'name' => 'welcome',
'subject' => 'Welcome to {{company}}',
'bodyHtml' => '<p>Hi {{name}}!</p>',
'variablesSchema' => [
'type' => 'object',
'required' => ['name', 'company'],
'properties' => [
'name' => ['type' => 'string'],
'company' => ['type' => 'string'],
],
],
]);
$mail->sendTemplate([
'templateId' => $tpl->id,
'to' => 'user@example.com',
'variables' => ['name' => 'Ada', 'company' => 'ACME'],
]);

Quota lifecycle events

useOrboto\Mail\Dto\QuotaState;
useOrboto\Mail\Dto\ConnectionRevokedEvent;
$mail->on('quota-warning', fn (QuotaState$q) => error_log("80%: {$q->current}/{$q->total}"));
$mail->on('quota-low', fn (QuotaState$q) => error_log("95%: {$q->current}/{$q->total}"));
$mail->on('quota-exhausted', fn (QuotaState$q) => error_log("100%: tier cap hit"));
$mail->on('connection-revoked', fn (ConnectionRevokedEvent$e) => error_log("disabled: {$e->message}"));

Each threshold event fires once per quota-reset period - a customer who lingers at 81 % doesn't get a quota-warning for every send.

Errors

Every non-2xx response surfaces as a typed exception:

useOrboto\Mail\Exception\OrbotoMailException;
useOrboto\Mail\Exception\QuotaExhaustedException;
useOrboto\Mail\Exception\PaymentRequiredException;
useOrboto\Mail\Exception\WalletUnavailableException;
useOrboto\Mail\Exception\SuppressedRecipientException;
useOrboto\Mail\Exception\ConnectionRevokedException;
try {
$mail->send([...]);
} catch (PaymentRequiredException$e) {
// Monthly quota used up + wallet balance too low - prompt a top-up
} catch (WalletUnavailableException$e) {
// Transient billing outage; send NOT dispatched - retry shortly
} catch (QuotaExhaustedException$e) {
// Render "upgrade your plan" - $e->getRemainingQuota() has the snapshot
} catch (SuppressedRecipientException$e) {
// Skip + log - recipient on suppression list
} catch (ConnectionRevokedException$e) {
// Disable the integration UX
} catch (OrbotoMailException$e) {
// Generic fallbackif ($e->isRetryable()) { /* server-side transient */ }
}

Overage billing (wallet). Once the monthly included quota is used up, above-quota sends draw on the account wallet. A successful overage send returns overage = true; an empty wallet throws PaymentRequiredException (402) and a brief billing outage throws WalletUnavailableException (503, fail-closed - the send is not dispatched). Both extend OrbotoMailException. Catch the specific classes BEFORE QuotaExhaustedException / OrbotoMailException (PHP matches the first compatible catch).

HTTP status	reason value	Exception
400	recipient_suppressed	SuppressedRecipientException
400	from_domain_not_authorized	OrbotoMailException - add domain at account.orboto.io/mail/sender-domains
401	connection_revoked	ConnectionRevokedException
402	payment_required	PaymentRequiredException - top up at account.orboto.io/mail/billing
402	base_quota / quota_exhausted_daily / etc.	QuotaExhaustedException
503	wallet_unavailable	WalletUnavailableException (auto-retried first)
502 / 503 / 504	any other	OrbotoMailException (auto-retried with backoff)

Configuration

Constructor options (all optional except apiKey):

$mail = newOrbotoMail([
'apiKey' => 'oms_live_xxx', // or set OMS_API_KEY env var'baseUrl' => 'https://mail.orboto.io/api', // default'timeout' => 10.0, // seconds per request'maxRetries' => 3, // transient-error retry budget'httpClient' => $myPsr18Client, // override the auto-discovered HTTP client'requestFactory' => $myPsr17RequestFactory,
'streamFactory' => $myPsr17StreamFactory,
]);

Environment variables (used when the corresponding option is omitted):

Variable	Default
OMS_API_KEY	(required)
OMS_BASE_URL	https://mail.orboto.io/api

HTTP client

The SDK uses PSR-18 + PSR-17. By default it auto-discovers an installed client via php-http/discovery. If you have Guzzle installed (composer require guzzlehttp/guzzle) it picks Guzzle. If you prefer Symfony's HTTP client or anything else PSR-18-compatible, install that package and discovery routes to it - or inject explicitly via the httpClient / requestFactory / streamFactory options.

Laravel

The SDK ships a Service-Provider + Facade + Notification Channel for Laravel 11+. Auto-discovery wires them in on composer require.

Publish the config:

php artisan vendor:publish --tag=orboto-mail-config

Then in code:

useOrboto\Mail\Laravel\OrbotoMailFacadeasOrbotoMail;
OrbotoMail::send([
'from' => config('mail.from.address'),
'to' => $user->email,
'subject' => 'Welcome',
'html' => view('mail.welcome', ['user' => $user])->render(),
]);

Or as a Notification Channel:

useOrboto\Mail\Laravel\OrbotoMailChannel;
class Welcome extends Notification
{
publicfunctionvia($notifiable): array
{
return [OrbotoMailChannel::class];
}
publicfunctiontoOrbotoMail($notifiable): array
{
return [
'from' => 'noreply@acme.orbo.to',
'to' => $notifiable->email,
'subject' => 'Welcome to ACME',
'html' => view('mail.welcome', ['user' => $notifiable])->render(),
];
}
}

API reference

All resources are accessible as public properties on the OrbotoMail instance:

Resource	Methods
$mail->suppression	check, add, remove, list
$mail->templates	list, get, create, update, remove
$mail->webhooks	list, get, create, update, remove, rotateSecret
$mail->sends	list, get
$mail->inbound	list, get
$mail->senderDomains	cloudflareDetect, cloudflareAutoSetup
$mail->apiKeys	list, get, create, revoke, rotate

Plus top-level send methods: send, sendBatch, sendTemplate, getQuota.

Full DTO list in src/Dto/. Every type is a readonly class with a fromArray() constructor for round-tripping over the wire.

Versioning

Releases stay in lockstep with the TypeScript SDK and the API backend - same vX.Y.Z tag bumps @orboto/mail (npm) + orboto/mail (Packagist) + the API container together. Patch releases are pure bug-fix / docs; minor releases add API surface; major releases imply a breaking change to the public method signatures (none yet).

License

MIT (see LICENSE.md). The PHP SDK is open-source; the OMS API backend it talks to is under the Sustainable Use License (see the repo root).

Support

• Docs: https://mail.orboto.io
• Customer portal: https://account.orboto.io/mail
• Issues: https://github.com/orboto/orboto-mail-php/issues