Skip to main content
The official mailkube Java SDK covers the whole send surface with zero runtime dependencies. The published POM has no <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

Replace X.Y.Z with the current version on Maven Central.
The artifact is a JPMS module named 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 with mk_. See Authentication for how to send it and keep it safe.

Send your first email

Create one client and reuse it for the life of the application. It holds no per-request state, and close() releases the HTTP client it created.

Configure the client

Pass the key explicitly, or omit it and let the client read MAILKUBE_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:
A client you inject belongs to you, so 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.
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 desktop or Android application, or in a public repository.

The response

A successful send returns two identifiers:
Use 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, and idempotentReplayed() tells you which happened:
The SDK does not retry on your behalf. See Idempotency.

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:
One client is safe to share across any number of threads, platform or virtual.

Scheduled sends

Set scheduledAt 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:
On an immediate send, 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:
Timestamps come back as the verbatim ISO-8601 strings the API sent. Call 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:
An unknown batch is a no-op reporting 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.
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 built with. To use another key, build another client.

Handling errors

Every failure is an unchecked exception descending from MailkubeException. 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:
The hierarchy under 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:
Verify against the raw received bytes. Parsing the body and re-serializing it reorders keys and normalizes whitespace, so the signature will not match. Read the input stream before any JSON binding touches it.
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:
It computes the HMAC exactly as 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 set MAILKUBE_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.