PHP SDK

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

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 for the surface you are calling.

Install

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

composer require sendmux/sdk:^2.1

composer require sendmux/sending:^2.1

composer require sendmux/mailbox:^2.1

composer require sendmux/management:^2.1

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

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

use Sendmux\Mailbox\ClientFactory;

$mailboxApi = ClientFactory::createMailboxAPIApiWithAccessToken(
    static fn (): string => getenv('SENDMUX_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.

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

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_`

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.sendmux.ai/api/v1 by default. Mailbox and Management use https://app.sendmux.ai/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

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

Developer tools

AI integrations

Sending

Receiving

Domains

Monitoring

Webhooks

Use cases

Integrations

Account and billing

Requirements

Install

OAuth access tokens

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

​OAuth access tokens

​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

OAuth access tokens

Create a client

Choose a surface

Shared API behaviour

Pagination

Retries and rate limits

Idempotency and ETags

Errors

Next steps