Install
Get your API key
Create a key for a verified domain in the dashboard. The key is a string that starts withmk_. See Authentication for how to send it and keep it safe.
Send your first email
Configure the client
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.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 anidempotencyKey to make a retry safe. A repeated request with the same key and body returns the result of the first send:
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
PassscheduledAt 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.batchId groups scheduled sends so they move or cancel together:
Your API key
$client->credential->info() returns the key the client authenticates with: its domain, organization, source-IP allowlist, plan and send-quota usage.
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 extendsMailkubeException. Transport failures raise ConnectionException; the server’s status chooses the API exception. Each carries errorName, message, statusCode, retryAfter and requestId.
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.
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:
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 setMAILKUBE_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.