Download the PHP package sendclipper/sendclipper-php without Composer

SendClipper PHP SDK

The official PHP library for the SendClipper email API.

PHP 8.1 or newer, with the curl and json extensions. No other dependencies.

Setup

Create an API key in the dashboard under API keys.

Send an email

Parameters and responses are plain arrays whose keys are the API's own field names (templateId, sendClass, ...), exactly as the API reference writes them.

from must be a bare address on a domain you verified in SendClipper. Each message has one recipient in to; for several, use batch->send.

Reply-To and attachments

replyTo is one address or a list of up to 10. content is the file's raw bytes, and the SDK base64-encodes it for you; if you already hold a base64 string, pass it as contentBase64 instead and it is sent as given (one or the other, never both). contentType is guessed from the filename when you leave it out. Limits: 10 MiB per file, 25 MiB of files per message, and your sending provider's own. Attachments are not accepted on a batch item; send those emails on their own. sandboxes->send() takes the same two fields.

Send with a template

Design and publish a template in the dashboard, then send it by id or by its send name:

A tag with no value and no {{tag|fallback}} is refused by name (template_variables_missing), never sent blank.

Send a batch

Up to 500 messages in one request. Each item is accepted or refused on its own:

Errors

API methods never throw for an API refusal or a network failure. They return a SendClipper\Result with data, error and headers, and exactly one of data and error is set. A Result destructures to [$data, $error]:

ErrorResponse has name (SendClipper's code: validation_failed, rate_limited, network_error, ...), message (a sentence for a person), statusCode (null when no answer arrived) and detail (code-specific facts).

The iterators (emails->iterate() and friends) throw an ApiException instead, since a loop has no error to hand back. $e->apiCode is the API's code and $e->status the HTTP status.

Retries and idempotency

Network errors, 429 and 5xx answers are retried twice with backoff, honouring Retry-After. Every JSON write carries an Idempotency-Key, and the API answers a repeated key with the first result for 24 hours. A retried send therefore never goes out twice.

To make your own retries safe as well (a queued job that runs again after a crash), pass a key that names the logical operation:

Request options

Every method takes request options as its last argument:

Client options: new SendClipper($key, ['baseUrl' => ..., 'timeout' => ..., 'maxRetries' => ..., 'defaultHeaders' => [...], 'transport' => ...]). baseUrl also reads SENDCLIPPER_BASE_URL. transport replaces the curl sender (a proxy, a test double): implement SendClipper\Transport\Transport.

Verify webhooks

SendClipper signs each delivery. Verify it against the raw body, before decoding:

In Laravel or Symfony pass $request->getContent() and $request->headers; a PSR-7 request works as the headers argument too. During a secret rotation a delivery carries two signatures and either one is accepted. A delivery signed more than five minutes away from now is refused. $sc->webhooks->verify(...) is the same function.

To test your handler locally, Webhook::signatureHeader($secret, $rawBody) builds a valid header.

Sandboxes

A sandbox traps mail while you develop: nothing is delivered.

Everything else

contacts->import() takes the file's contents (file_get_contents('contacts.csv')), and templates->assets->upload() the image's bytes. Management routes need a key with Full access. A sending-only key can call emails->send and batch->send.

Full API reference: https://sendclipper.com/docs.

License

MIT