Download the PHP package mailblastr/mailblastr without Composer

mailblastr-php

Official PHP SDK for the MailBlastr email API — send transactional and marketing email from your own verified domain.

Requirements

PHP 8.1+ with the curl and json extensions. No other runtime dependencies.

Install

Usage

Every method returns the decoded JSON response as an associative array. Any non-2xx response throws Mailblastr\Exceptions\MailblastrException carrying the API error shape:

Branch on getName(), and read getStatusCode() from the response rather than inferring it from the name — a handler may return a name with a non-default status (a missing User-Agent, for example, is validation_error with a 403, and max_active_keys is a 429). Messages are sanitized human text and change freely, so never match on them.

Some errors carry more than that envelope. The extras are accessors on the exception and return null on an ordinary error:

$e->getBody() is the whole parsed error body, so a field newer than this SDK version is still reachable.

Attachments

Attach files by hosted URL (path, fetched at send time) or inline base64 (content):

Options

timeout and maxRetries configure the default curl transport only; a transport you supply is used as-is.

Resources

The client exposes one property per resource, each following a consistent (create / get / list / update / remove, plus resource-specific verbs) shape:

emails (with nested emails->receiving), batch, domains, audiences, contacts, contactProperties, campaigns, segments, topics, templates, automations, webhooks, logs, events, apiKeys (list only — see below), polls.

API keys are managed in the dashboard

apiKeys->list() is the whole API-key surface: the SDK deliberately exposes no method to create, re-scope or revoke a key. Key lifecycle belongs to a signed-in dashboard session, and the API enforces it — POST /api-keys, PATCH /api-keys/:id and DELETE /api-keys/:id answer 403 dashboard_only to any API-key caller, whatever its permission. That is the point: a key that leaks cannot mint itself a replacement, widen its own access, or revoke the keys you would use to shut it off. Create and revoke keys at mailblastr.com.

Topics

Topics let contacts manage granular subscriptions (e.g. "Product updates").

Automations

Build multi-step automations triggered by events, then inspect their runs.

Every automation belongs to one of your sending domains — domain is REQUIRED on create, and events->send() names the domain it targets, so the same event name across several products can never trigger the wrong automation.

Webhooks

Subscribable events: email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.opened, email.clicked, email.failed, email.scheduled, email.suppressed, email.received, email.replied, email.unsubscribed, contact.created, contact.updated, contact.deleted, domain.created, domain.updated, domain.deleted. Anything else is rejected with a 422.

Verify a delivery's Svix-style signature in your endpoint (a pure local HMAC-SHA256 computation — no HTTP request). Pass the EXACT raw request body:

Also available without a client: Mailblastr\WebhookSignature::verify(...).

Logs

Pagination

list() methods accept optional cursor pagination — ['limit' => …, 'after' => …, 'before' => …] — appended as a query string:

limit must be an integer between 1 and 100 (default 20). after and before are item ids and are mutually exclusive — passing both is a 422. Every list response is ['object' => 'list', 'has_more' => bool, 'data' => [...]]; there is no total and no next cursor, so page forward with the last data item's id as after. An unknown cursor returns an empty page, not an error.

Note that some list endpoints skip the 20-row default when you pass no pagination params at all, returning everything up to a hard ceiling of 1,000 rows instead — domains, apiKeys, topics, campaigns, contacts, contactProperties, segments, polls, segments->contacts(), contacts->listSegments(), contacts->getTopics() and emails->receiving->listAttachments(). Do not read that as "the whole collection": past 1,000 rows the response is truncated and has_more is true, so page with limit + after rather than relying on one unpaginated call. The other direction is just as uneven: templates, webhooks, audiences, automations, automations->runs() and events always cap an unpaginated call at 20.

Idempotency

Pass an idempotency key to safely retry a send:

The key must be 1–255 characters, measured after the server trims it — 255, not 256. Mailblastr\Client::IDEMPOTENCY_KEY_MAX_LENGTH carries that number. The SDK sends the key verbatim and lets the server be the authority: an out-of-range key comes back as a 400 invalid_idempotency_key.

Replaying a key returns the original response; reusing it with a different payload is a 409. Only emails->send() and batch->send() honour it — every other endpoint, including events->send(), still accepts an idempotencyKey option and forwards it, but the API ignores it there, so a retry creates a second resource. De-duplicate on your side instead.

Rate limits

Only the /emails SEND routes are rate limited: 30 requests per minute per IP. Reads (GET /emails, GET /emails/:id, the receiving subtree and attachment listings) are NOT subject to that cap — paging a large list no longer risks a

429. Capped responses carry RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers on success too. automations->createWithAi() is separately limited to 20 requests per minute per account. The default transport retries a 429 or 503 automatically (honouring Retry-After) up to maxRetries times.

Testing

The HTTP transport is swappable — pass any Mailblastr\Transport\TransportInterface implementation as 'transport' to fake responses in your tests. A real custom transport must send the headers it is handed verbatim: the API rejects any request without a non-empty User-Agent with a 403 before it even authenticates.

The SDK's own test suite (no framework needed) runs with:

Documentation

Full docs: https://www.mailblastr.com/docs

License

MIT