<dependencies> block, and the standard library covers everything, including JSON.
It requires JVM 25 or newer. The SDK ships one synchronous client and leaves concurrency to virtual threads. That only became safe once JEP 491 removed monitor pinning in JDK 24, and 25 is the LTS release above that line. See Concurrency.
Install
ReplaceX.Y.Z with the current version on Maven Central.
com.mailkube. It works on the module path and on the classpath alike:
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
close() releases the HTTP client it created.
Configure the client
Pass the key explicitly, or omit it and let the client readMAILKUBE_API_KEY:
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. It is appended after the SDK’s own token, so both are visible: mailkube-java/2.1.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.
Pass your own HttpClient to add a proxy, an SSL context, instrumentation, or a stub in tests:
MailkubeClient.close() leaves it open. The per-request timeout rides on each request and still applies to an injected client. Only the connect timeout is yours to set once you inject one.
The response
A successful send returns two identifiers:id() to correlate the message with webhook events. Use messageId() in In-Reply-To and References to thread replies.
Recipients, content and attachments
to, cc, bcc and replyTo each take a list. Supply html, text, or both. Attachment content is raw bytes:
To send a saved template, pass
templateId(...) (and optionally templateVersion(...)) with variables(...), and omit html/text. See Sending your first email for template behavior.Idempotent sends
Set an idempotency key on anything you might retry. A retried request replays the original response, andidempotentReplayed() tells you which happened:
Concurrency
The client is synchronous. On JVM 25 a virtual thread per call costs almost nothing. That is why the SDK ships no second, asynchronous copy of every method:Scheduled sends
SetscheduledAt to an Instant, or an ISO-8601 string with an offset, and the message is accepted now and delivered later. It must be in the future and within your plan’s scheduling horizon:
isScheduled() is false and status(), scheduledAt() and batchId() stay null.
Managing what is scheduled
list returns one page. iterateAll returns a lazy Stream that follows the links the API issues, so abandoning it early costs no further request:
Instant.parse if you want objects. recipients is a summary string ("[email protected] +2"), not a list: the full recipient set stays server-side with the frozen payload.
Whole batches move or cancel together:
0, not an error. See Scheduled emails for horizons and listing windows.
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 built with. To use another key, build another client.
Handling errors
Every failure is an unchecked exception descending fromMailkubeException. One catch at the edge covers the category you care about. A transport failure that produced no response at all raises ConnectionException and is deliberately not an API error:
MailkubeException includes BadRequestException (400), AuthenticationException (403), NotFoundException (404), ConflictException (409), InvalidRequestException (422), RateLimitException (429), ServerException (5xx), and ApiException, which is both the fallback for any other status and the supertype of all of them.
Three more sit beside ApiException rather than under it, because no response produced them. ConnectionException covers a transport failure, SignatureVerificationException a rejected webhook, and ConfigurationException a missing API key or otherwise unusable configuration.
ErrorName lists every documented errorName as a constant, but the value stays a plain String. A name this release has never heard of is reported verbatim. See Errors.
Quote requestId() when reporting a failure to support.
Receiving webhooks
Webhooks.verifySignature is a dependency-free HMAC check over the raw request body; it returns those same bytes, which compose with parseEvent in one expression. It needs no client instance and no HTTP, and drops into any framework’s handler:
WebhookEvent is a sealed interface. A switch with no default arm will not compile until it handles every event type, and the compiler tells you when a new one appears. The example above takes the default arm instead, which handles two cases and ignores the rest. Typed events 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.
Two rules keep a receiver working across releases. A type this version does not recognize parses as UnknownEvent instead of raising. raw() on every event returns the whole decoded payload. A field added after your installed release still reaches you, with no typed accessor for it yet. For the same reason, event type, status and reason values stay String and never become enums.
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 handler will accept without waiting on a real delivery. It takes the payload as byte[], like verifySignature, and returns the sha256=<hex> header value:
Webhooks.verifySignature checks it, so a fixture built this way cannot drift from the verifier. It takes the timestamp you give it and does not judge its freshness. Pass a stale one and Webhooks.verifySignature rejects it, which is how you assert your replay handling.
Logging and metrics
Silent unless you ask. Turn on one line per exchange with a level, or setMAILKUBE_LOG:
MAILKUBE_LOG holds a level name, not a flag: MAILKUBE_LOG=WARNING suppresses the quieter records. Records go through System.Logger and land in whatever logging framework your application already runs, with no adapter and no extra dependency.
Enabling is per client. Two clients in one application can differ, and no library on your classpath can turn logging on for a client it does not own.
Each record carries the method, path, status, request id and elapsed time, and only those. A send body carries recipient addresses, subject lines, rendered HTML and template variables. No redaction rule makes those safe in an application log, so the SDK never logs bodies or headers and ships no redaction helper.
To feed metrics, take the same information as a callback:
error is non-null only when no response arrived at all; a 4xx or 5xx is a response and comes through with a status and no error. The observer runs on the thread that made the request, so keep it cheap. One that throws is reported and ignored; the send completes.
Next steps
Scheduled emails
Horizons, listing windows, and how a
batchId moves or cancels a group.Webhooks
The payload behind every sealed event type, and the signature scheme.
API reference
Every send field
SendEmailParams maps to, with error codes and rate limits.Errors
Each documented
errorName, its meaning, and how to react.