Skip to main content
The official mailkube PHP SDK wraps the whole send surface behind named arguments and readonly models. It requires PHP 8.3+ and talks PSR-18, shipping no HTTP client of its own and slotting into whatever your application already uses.

Install

The package depends on PSR interfaces, not implementations. If your project does not already have a PSR-18 client and PSR-17 factories, add one:
Anything installed is discovered automatically.

Get your API key

Create a key for a verified domain in the dashboard. The key is a string that starts with mk_. See Authentication for how to send it and keep it safe.

Send your first email

Every verb takes named arguments. A call reads like the API reference and is checked by your editor and by static analysis. Order never matters; only the names do.

Configure the client

If you are building something on top of this SDK, such as a CLI, an internal service, or a framework integration, set userAgentSuffix: to your own name/version, so both are visible: mailkube-php/1.3.0 my-cli/1.0.0. The API requires a User-Agent on every request; the SDK already sends one, and this identifies your layer within it.
Create one client and reuse it. It holds no mutable state after construction. A container-bound singleton shared by every request is the intended pattern.
PSR-18 has no timeout API, so timeout: applies to a client the SDK builds for you. If you inject your own httpClient:, it keeps the timeout you configured on it.
Your API key can send email on your behalf. Keep it server-side, injected from a secrets manager or environment variable. Never ship it in a public repository or anything that reaches a browser.

The response

Recipients, content and attachments

to, cc, bcc and replyTo each take a single address or an array of them. A send carries either raw content (html and/or text) or a saved template.
Attachment::fromBytes() base64-encodes for you; use Attachment::fromBase64() when you encoded it yourself. Tags are denormalized onto the sending log for filtering and export, and they ride along on delivery webhooks. To send a saved template instead, pass templateId with templateVersion and variables in place of html/text.

Idempotent sends

Pass an idempotencyKey to make a retry safe. A repeated request with the same key and body returns the result of the first send:
The key travels as the Idempotency-Key header. See Idempotency for the full semantics.
The SDK never retries on your behalf. A RateLimitException carries retryAfter and a ServerException is safe to retry with backoff. The decision stays yours, along with the idempotency key that makes it safe.

Scheduled sends

Pass scheduledAt to have the message delivered later. The send is acknowledged 202 and stays manageable until it is due.
scheduledAt accepts a DateTimeInterface or an ISO-8601 string with an offset.

Managing what is scheduled

list() returns one page, exposed as $page->data, $page->pagination and $page->hasMore(). To walk every page, use iterAll(), which follows the links the server issues and fetches each page as the loop reaches it:
$email->recipients is a summary string such as "[email protected] +2", not an array. The full recipient list stays server-side with the frozen message payload.
A batchId groups scheduled sends so they move or cancel together:
See Scheduled emails for the scheduling horizon and listing window.

Your API key

$client->credential->info() returns the key the client authenticates with: its domain, organization, source-IP allowlist, plan and send-quota usage.
The key is checked exactly as a send checks it, so one call confirms a key works before your first send. A key that cannot send throws AuthenticationException with the error name invalid_api_key, and Checking a key lists the causes. Each call counts as a use of the key, and plan and quota figures can be up to 30 seconds old. plan is null when the organization has no subscription. A plan without a daily limit lists emails_per_month only, and remaining counts recipients, not messages. The call has a rate limit of its own for each key. The client keeps the key it was constructed with. To use another key, construct another client.

Handling errors

Every failure extends MailkubeException. Transport failures raise ConnectionException; the server’s status chooses the API exception. Each carries errorName, message, statusCode, retryAfter and requestId.
The hierarchy under MailkubeException includes BadRequestException, AuthenticationException, NotFoundException, ConflictException, InvalidRequestException, RateLimitException, ServerException and ConnectionException. ErrorName lists every documented errorName as a constant, but the value stays a plain string. An unrecognized name is reported verbatim. See Errors. Quote requestId when reporting a failure to support.

Receiving webhooks

Webhooks::verify() checks the signature over the raw request body and returns a typed event. It needs no client instance and no HTTP, and drops into any framework’s controller.
Verify against the raw received bytes. Decoding the JSON and re-encoding it changes the bytes, and the signature will not match.
Typed classes exist for email.sent, email.delivered, email.bounced, email.delivery_delayed, email.suppressed, email.scheduled, email.failed, email.opened, email.clicked, domain.status and webhook.status. Anything newer arrives as an UnknownEvent instead of raising, and $event->raw always holds the whole decoded payload. A receiver that logs or forwards events never loses a field. X-Webhook-Id is stable across retries. Deduplicate on it before acting. See Webhooks for the full event catalog.

Signing, for your tests

Production code verifies; it never signs. Webhooks::sign() is the other half, for building a request your controller will accept without waiting on a real delivery:
Sign the exact string you will send; a re-encoding of parsed JSON changes the bytes. Webhooks::sign() computes the HMAC exactly as Webhooks::verify() checks it, so a fixture built this way cannot drift from the verifier.

Logging

Silent by default. Pass any PSR-3 logger, or set MAILKUBE_LOG to a level:
MAILKUBE_LOG carries a level, not a flag, so setting it to warning suppresses the SDK’s request and response records. Every line masks the Authorization and Idempotency-Key headers, and message bodies stay out of the log.

Next steps

Scheduled emails

The horizon and listing window behind scheduledAt, and how a batchId groups sends.

Webhooks

Every event class Webhooks::verify() can return, and the signing scheme.

API reference

Every named argument the send endpoint accepts, with its error codes and rate limits.

Errors

The meaning of each errorName and the right reaction to it.