> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP SDK

> Install and configure the Qubrics PHP SDK packages.

Use the PHP SDK when your application needs Composer packages for one or more Qubrics API surfaces.

> [!NOTE]
>
> For API-key authentication, Sending clients accept a send-capable `smx_mbx_` key or owner-approved Sending-resource `smx_agent_` token. Mailbox clients accept
> `smx_mbx_` keys or scoped `smx_agent_` tokens. Management API-key clients require
> team-scoped `smx_root_` keys.

## Requirements

* PHP 8.2 or newer.
* Composer.
* An API key or [REST OAuth grant](https://sendmux.ai/docs/developer-tools/oauth.md) for the surface you are calling.

## Install

Install the umbrella package when one application needs more than one API surface.

```bash Umbrella theme={null}
composer require qubrics/sdk:^3.0
```

```bash Sending theme={null}
composer require qubrics/sending:^3.0
```

```bash Mailbox theme={null}
composer require qubrics/mailbox:^3.0
```

```bash Management theme={null}
composer require qubrics/management:^3.0
```

## OAuth access tokens

`ClientFactory::createMailboxAPIApiWithAccessToken()` accepts a bare token or a callable returning one. Every Sending, Mailbox and Management factory has a corresponding `WithAccessToken` method.

```php theme={null}
<?php

require __DIR__ . '/vendor/autoload.php';

use Qubrics\Mailbox\ClientFactory;

$mailboxApi = ClientFactory::createMailboxAPIApiWithAccessToken(
    static fn (): string => getenv('QUBRICS_ACCESS_TOKEN') ?: ''
);
```

Token providers run on each request and retry. OAuth clients do not follow redirects. Token storage and refresh coordination remain your application's responsibility; see [OAuth for REST APIs](https://sendmux.ai/docs/developer-tools/oauth.md#refresh-and-disconnect).

> [!NOTE]
>
> OAuth factories attach credentials through their HTTP client. If you build a request with a `*Request()` method, send it through `ClientFactory::httpClient(accessToken: $token)`; the request object itself has no factory OAuth header.

## Create a client

PHP packages expose factory methods for each generated API group.

```php Sending theme={null}
<?php

require __DIR__ . '/vendor/autoload.php';

use Qubrics\Sending\ClientFactory;

$emails = ClientFactory::createEmailsApi(
    getenv('QUBRICS_MAILBOX_API_KEY') ?: ''
);
```

```php Mailbox theme={null}
<?php

require __DIR__ . '/vendor/autoload.php';

use Qubrics\Mailbox\ClientFactory;

$mailboxApi = ClientFactory::createMailboxAPIApi(
    getenv('QUBRICS_MAILBOX_API_KEY') ?: ''
);
```

```php Management theme={null}
<?php

require __DIR__ . '/vendor/autoload.php';

use Qubrics\Management\ClientFactory;

$mailboxes = ClientFactory::createMailboxesApi(
    getenv('QUBRICS_ROOT_API_KEY') ?: ''
);
```

## Choose a surface

| Surface | Package | Factory examples | API key |
| - | - | - | - |
| Sending | `qubrics/sending` | `createEmailsApi`, `createMetaApi` | `smx_mbx_` or owner-approved `smx_agent_` with `email.send` |
| Mailbox | `qubrics/mailbox` | `createMailboxAPIApi` | `smx_mbx_` or scoped `smx_agent_` |
| Management | `qubrics/management` | `createMailboxesApi`, `createDomainsApi`, `createWebhooksApi` | `smx_root_` |

> [!NOTE]
>
> Durable `smx_agent_` tokens are mailbox-compatible and include `mailbox.read`
> and `email.receive`, not `email.send`. After owner acceptance and approval,
> exchange the durable token for a one-hour Sending-resource token before sending.

Sending uses `https://smtp.qubrics.com/api/v1` by default. Mailbox and Management use `https://app.qubrics.com/api/v1`.

## Shared API behaviour

API-key factories validate key prefixes. Both credential modes configure bearer auth and add retry middleware to generated API clients.

### Pagination

List responses use cursor pagination with `pagination.has_more` and `pagination.next_cursor`. The core package exports `Pagination::iterate()` for cursor iteration when you wrap a page-fetching function.

### Retries and rate limits

Surface clients use `RetryMiddleware::create()` by default. It retries safe methods and retry-safe `POST` requests that include `Idempotency-Key`, then honours `Retry-After` and `X-RateLimit-Reset` response headers.

Pass `RetryOptions` into a factory method to change attempts, local backoff, jitter, or `maxElapsedMilliseconds`. Server retry delays are never shortened to fit local backoff limits. If another attempt would exceed the retry budget, the client returns the last response with its retry metadata; the budget does not interrupt an in-flight request. Responses with `error.retryable: false` are not retried.

### Idempotency and ETags

Use core header helpers when a generated operation accepts custom headers.

```php theme={null}
<?php

use Qubrics\Core\Headers;

$headers = array_merge(
    Headers::idempotency('order-123'),
    Headers::conditional(ifMatch: $etag)
);
```

Use `Idempotency-Key` for retry-safe mutating requests. Use `If-Match` and `If-None-Match` with single-resource endpoints that support ETags.

### Errors

The core package defines `QubricsApiError`. Use `ErrorMapper::fromThrowable()` when you need to normalise a generated exception into the Qubrics error shape.

Use the mapped error code, retryability, status, and request ID when deciding whether to retry or contact support.

## Next steps

> [card] [SDK overview](https://sendmux.ai/docs/developer-tools/sdks)
>
> Choose the right package family and API surface.

> [card] [Versioning and support](https://sendmux.ai/docs/developer-tools/sdks/versioning-support.md)
>
> Check compatibility, support, and upgrade guidance.

> [card] [Management API](https://sendmux.ai/docs/api/introduction.md)
>
> Review the Management API contract used by `qubrics/management`.

> [card] [API keys](https://sendmux.ai/docs/account/api-keys.md)
>
> Create and scope the credentials used by SDK clients.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.