PHP SDK

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

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 clients require team-scoped smx_root_ keys.

Requirements

PHP 8.2 or newer.
Composer.
A Sendmux API key for the surface you are calling.

Install

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

composer require sendmux/sdk:^1.0

composer require sendmux/sending:^1.0

composer require sendmux/mailbox:^1.0

composer require sendmux/management:^1.0

Create a client

PHP packages expose factory methods for each generated API group.

<?php

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

use Sendmux\Sending\ClientFactory;

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

<?php

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

use Sendmux\Mailbox\ClientFactory;

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

<?php

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

use Sendmux\Management\ClientFactory;

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

Choose a surface

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

Pre-claim smx_agent_ tokens are mailbox-compatible only. Owner-approved Sending-resource smx_agent_ tokens can send. Pre-claim self-registered agent tokens include mailbox.read and email.receive, not email.send.

Sending uses https://smtp.sendmux.ai/api/v1 by default. Mailbox and Management use https://app.sendmux.ai/api/v1.

Shared API behaviour

Surface factories validate API key prefixes, 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, delays, or jitter.

Idempotency and ETags

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

<?php

use Sendmux\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 SendmuxApiError. Use ErrorMapper::fromThrowable() when you need to normalise a generated exception into the Sendmux error shape. Use the mapped error code, retryability, status, and request ID when deciding whether to retry or contact support.

Next steps

SDK overview

Choose the right package family and API surface.

Versioning and support

Check compatibility, support, and upgrade guidance.

Management API

Review the Management API contract used by sendmux/management.

API keys

Create and scope the credentials used by SDK clients.

Getting started

SDKs and CLI

Use cases

Integrations

AI integrations

Teams and access

Sending

Receiving

Monitoring

Webhooks

Requirements

Install

Create a client

Choose a surface

Shared API behaviour

Retries and rate limits

Idempotency and ETags

Errors

Next steps

SDK overview

Versioning and support

Management API

API keys

​Requirements

​Install

​Create a client

​Choose a surface

​Shared API behaviour

​Pagination

​Retries and rate limits

​Idempotency and ETags

​Errors

​Next steps

SDK overview

Versioning and support

Management API

API keys

Requirements

Install

Create a client

Choose a surface

Shared API behaviour

Pagination

Retries and rate limits

Idempotency and ETags

Errors

Next steps