### Install Orboto Mail PHP SDK

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Install the SDK using Composer. Requires PHP 8.2+ and a PSR-18 HTTP client.

```bash
composer require orboto/mail
```

--------------------------------

### Quick Start: Send an Email

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Initialize the OrbotoMail client with your API key and send a single email. Access the message ID, status, and quota usage from the result.

```php
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'    => '<h1>Welcome!</h1>',
]);

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

--------------------------------

### API Reference - Sender Domains Resource

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Manage sender domains. Includes methods for Cloudflare detection and automatic setup.

```APIDOC
## API reference

| Resource | Methods |
|---|---|
| `$mail->senderDomains` | `cloudflareDetect`, `cloudflareAutoSetup` |
```

--------------------------------

### API Reference - Sends Resource

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Retrieve information about sent emails. Supports listing and getting details of individual send operations.

```APIDOC
## API reference

| Resource | Methods |
|---|---|
| `$mail->sends`         | `list`, `get` |
```

--------------------------------

### Send Email via OrbotoMail Facade in Laravel

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Use the OrbotoMail facade to send emails within a Laravel application. Ensure the configuration is published using 'php artisan vendor:publish --tag=orboto-mail-config'. This example demonstrates sending a basic email with subject and HTML content.

```php
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(),
]);
```

--------------------------------

### Constructor Options

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Initialize the OrbotoMail client with various configuration options. The apiKey is mandatory, while others have defaults or can be set via environment variables.

```APIDOC
## Constructor Options

Constructor options (all optional except `apiKey`):

```php
$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):

| Variable | Default |
|---|---|
| `OMS_API_KEY` | *(required)* |
| `OMS_BASE_URL` | `https://mail.orboto.io/api` |
```

--------------------------------

### Initialize OrbotoMail with Constructor Options

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Instantiate the OrbotoMail client using an array of configuration options. The apiKey is mandatory, while others like baseUrl, timeout, and maxRetries are optional and have defaults. You can also inject custom PSR-18/17 compatible HTTP client components.

```php
$mail = new OrbotoMail([
    'apiKey'        => 'oms_live_xxx',
    'baseUrl'       => 'https://mail.orboto.io/api',
    'timeout'       => 10.0,
    'maxRetries'    => 3,
    'httpClient'    => $myPsr18Client,
    'requestFactory' => $myPsr17RequestFactory,
    'streamFactory' => $myPsr17StreamFactory,
]);
```

--------------------------------

### Create and Send with Templates

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Define email templates with dynamic variables and schemas. Send emails using these templates by providing the template ID and variable values.

```php
$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'],
]);
```

--------------------------------

### API Reference - Webhooks Resource

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Manage webhook configurations. Supports listing, retrieving, creating, updating, removing webhooks, and rotating the secret key.

```APIDOC
## API reference

| Resource | Methods |
|---|---|
| `$mail->webhooks`      | `list`, `get`, `create`, `update`, `remove`, `rotateSecret` |
```

--------------------------------

### Send a Batch of Emails

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Send multiple emails in a single request, capped at 100 messages. Inspect the batch results for individual success or failure, and check the summary for overall counts.

```php
$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.";
```

--------------------------------

### Register Quota Lifecycle Event Listeners

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Attach listeners to specific quota events like 'quota-warning', 'quota-low', 'quota-exhausted', and 'connection-revoked'. These events fire once per quota-reset period.

```php
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}"));
```

--------------------------------

### API Reference - Templates Resource

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Manage email templates. Operations include listing, retrieving, creating, updating, and removing templates.

```APIDOC
## API reference

| Resource | Methods |
|---|---|
| `$mail->templates`     | `list`, `get`, `create`, `update`, `remove` |
```

--------------------------------

### Top-Level Send Methods

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Direct methods for sending emails, including single sends, batch sends, template-based sends, and retrieving quota information.

```APIDOC
## API reference

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

--------------------------------

### API Reference - API Keys Resource

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Manage API keys for your Orboto account. Operations include listing, retrieving, creating, revoking, and rotating keys.

```APIDOC
## API reference

| Resource | Methods |
|---|---|
| `$mail->apiKeys`       | `list`, `get`, `create`, `revoke`, `rotate` |
```

--------------------------------

### Laravel Integration - Sending Mail

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Send emails using the Orboto Mail SDK within a Laravel application via the Facade.

```APIDOC
## Laravel

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

Publish the config:

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

Then in code:

```php
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(),
]);
```
```

--------------------------------

### Implement OrbotoMailChannel for Laravel Notifications

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Integrate Orboto Mail as a notification channel in Laravel. This involves defining the 'via' method to return OrbotoMailChannel::class and implementing 'toOrbotoMail' to return the email payload. This allows using Orboto Mail for sending notifications.

```php
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 - Inbound Resource

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Access inbound email data. Supports listing and retrieving inbound email records.

```APIDOC
## API reference

| Resource | Methods |
|---|---|
| `$mail->inbound`       | `list`, `get` |
```

--------------------------------

### API Reference - Suppression Resource

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Manage email suppression lists. Available methods include checking, adding, removing, and listing suppressed email addresses.

```APIDOC
## API reference

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

| Resource | Methods |
|---|---|
| `$mail->suppression`   | `check`, `add`, `remove`, `list` |
```

--------------------------------

### Laravel Integration - Notification Channel

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Integrate Orboto Mail as a Notification Channel in Laravel for sending notifications.

```APIDOC
## Laravel

Or as a Notification Channel:

```php
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(),
        ];
    }
}
```
```

--------------------------------

### Handle Orboto Mail Exceptions

Source: https://github.com/orboto/orboto-mail-php/blob/develop/README.md

Catch specific exceptions like QuotaExhaustedException, SuppressedRecipientException, and ConnectionRevokedException for granular error handling. A generic OrbotoMailException catches other API errors.

```php
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 */ }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.