PHPackages                             orboto/mail - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. orboto/mail

ActiveLibrary[Mail & Notifications](/categories/mail)

orboto/mail
===========

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.

0.6.1(2w ago)039↓100%MITPHPPHP ^8.2

Since May 17Pushed 2w agoCompare

[ Source](https://github.com/orboto/orboto-mail-php)[ Packagist](https://packagist.org/packages/orboto/mail)[ Docs](https://mail.orboto.io)[ RSS](/packages/orboto-mail/feed)WikiDiscussions develop Synced 1w ago

READMEChangelogDependencies (10)Versions (7)Used By (0)

@orboto/mail — PHP SDK
======================

[](#orbotomail--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`](https://www.npmjs.com/package/@orboto/mail) — release versions stay in lockstep.

Install
-------

[](#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
-----------

[](#quick-start)

```
use Orboto\Mail\OrbotoMail;

$mail = new OrbotoMail(['apiKey' => $_ENV['OMS_API_KEY']]);

$result = $mail->send([
    'from'    => 'noreply@acme.orbo.to',
    'to'      => 'user@example.com',
    'subject' => 'Welcome',
    'html'    => 'Welcome!',
]);

echo $result->messageId;       // server-issued message id
echo $result->status;          // 'queued' at success-time
echo $result->remainingQuota->percentUsed; // 0.0 .. 1.x
```

Get an API key at [account.orboto.io/mail/api-keys](https://account.orboto.io/mail/api-keys).

Send a batch
------------

[](#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->results as $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
---------

[](#templates)

```
$tpl = $mail->templates->create([
    'name' => 'welcome',
    'subject' => 'Welcome to {{company}}',
    'bodyHtml' => 'Hi {{name}}!',
    '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
----------------------

[](#quota-lifecycle-events)

```
use Orboto\Mail\Dto\QuotaState;
use Orboto\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
------

[](#errors)

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

```
use Orboto\Mail\Exception\OrbotoMailException;
use Orboto\Mail\Exception\QuotaExhaustedException;
use Orboto\Mail\Exception\SuppressedRecipientException;
use Orboto\Mail\Exception\ConnectionRevokedException;

try {
    $mail->send([...]);
} 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 fallback
    if ($e->isRetryable()) { /* server-side transient */ }
}
```

HTTP statusreason valueException400`recipient_suppressed``SuppressedRecipientException`400`from_domain_not_authorized``OrbotoMailException` — add domain at [`account.orboto.io/mail/sender-domains`](https://account.orboto.io/mail/sender-domains)401`connection_revoked``ConnectionRevokedException`402`base_quota` / `quota_exhausted_daily` / `overage_cap` / etc.`QuotaExhaustedException`502 / 503 / 504any`OrbotoMailException` (auto-retried with backoff)Configuration
-------------

[](#configuration)

Constructor options (all optional except `apiKey`):

```
$mail = new OrbotoMail([
    '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):

VariableDefault`OMS_API_KEY`*(required)*`OMS_BASE_URL``https://mail.orboto.io/api`HTTP client
-----------

[](#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
-------

[](#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:

```
use Orboto\Mail\Laravel\OrbotoMailFacade as OrbotoMail;

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

Or as a Notification Channel:

```
use Orboto\Mail\Laravel\OrbotoMailChannel;

class Welcome extends Notification
{
    public function via($notifiable): array
    {
        return [OrbotoMailChannel::class];
    }

    public function toOrbotoMail($notifiable): array
    {
        return [
            'from'    => 'noreply@acme.orbo.to',
            'to'      => $notifiable->email,
            'subject' => 'Welcome to ACME',
            'html'    => view('mail.welcome', ['user' => $notifiable])->render(),
        ];
    }
}
```

API reference
-------------

[](#api-reference)

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

ResourceMethods`$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
----------

[](#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
-------

[](#license)

MIT (see [LICENSE.md](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
-------

[](#support)

- Docs:
- Customer portal:
- Issues:

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance97

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

5

Last Release

16d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/37f22066b7621f627f3a61878dd2e91ba3363043b07e33baf63ea8fc2de027a4?d=identicon)[schemann](/maintainers/schemann)

---

Tags

laravelsmtpsesgdprtransactional emailorboto

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/orboto-mail/health.svg)

```
[![Health](https://phpackages.com/badges/orboto-mail/health.svg)](https://phpackages.com/packages/orboto-mail)
```

###  Alternatives

[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35729.6k2](/packages/telnyx-telnyx-php)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k11](/packages/tempest-framework)[cakephp/cakephp

The CakePHP framework

8.8k19.1M1.7k](/packages/cakephp-cakephp)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

84735.1k](/packages/flow-php-flow)[gotenberg/gotenberg-php

A PHP client for interacting with Gotenberg, a developer-friendly API for converting numerous document formats into PDF files, and more!

3835.9M26](/packages/gotenberg-gotenberg-php)[laudis/neo4j-php-client

Neo4j-PHP-Client is the most advanced PHP Client for Neo4j

185671.3k41](/packages/laudis-neo4j-php-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)