Skip to main content
mailkube-spring-boot is a starter over the Java SDK: auto-configuration gives you Spring’s MailSender backed by mailkube, plus an opt-in webhook endpoint that publishes application events. Requires Java 25+ and Spring Boot 3.5.0+. The Java floor comes from the SDK, not from Spring: Boot itself runs on Java 17, but the SDK’s class files are compiled for a Java 25 toolchain and cannot load on an earlier JVM.

Install

Replace X.Y.Z with the current version on Maven Central.
Auto-configuration does the rest. Set the key:
or leave it out and let the SDK read MAILKUBE_API_KEY from the environment.

Send

Inject Spring’s MailSender and send exactly as you do today:

The full-fidelity path

SimpleMailMessage has no HTML body and no attachments, permanently; that is Spring’s type, not a limit of the starter. For everything else, inject MailkubeMailSender. It implements MailSender for compatibility and adds send(SendEmailParams), which carries every field the Java SDK can send:
Both surfaces are synchronous, because MailSender is. To send off the request thread, annotate your own caller with @Async; that decision belongs to your application, and the starter does not make it for you. An inline cid: image arrives as an ordinary attachment: the API’s attachment model carries no content id.

Handle failures

Every SDK failure is translated into Spring’s own MailException hierarchy, which is what keeps spring-retry, Spring Integration’s mail adapters and @ControllerAdvice handlers working: The original exception is always preserved as the cause, and retryability is deliberately not re-encoded: a 429 or a 5xx carries the SDK’s own type underneath, where that taxonomy belongs. send(SimpleMailMessage...) sends each message independently. A partial failure throws a MailSendException whose getFailedMessages() names exactly which ones did not go.

Configure

An unset property is omitted, never passed as null, and the SDK’s own environment fallbacks stay in charge. Define your own MailkubeClient bean, or any MailSender bean, and the starter backs off entirely; that is the seam for a custom userAgentSuffix or observer. spring-web is an optional dependency: a batch or worker application gets the mail sender without being pulled onto a web stack, and the webhook controller is not registered.

Receiving webhooks

The webhook endpoint is off by default. Adding a mail dependency should not open an HTTP route. Opt in:
The controller verifies each delivery over the raw request bytes and publishes one application event. The SDK’s sealed event type is what you switch on, and an unmodeled type still arrives with its payload intact:
Listeners are synchronous by default, which is Spring’s own default; add @Async to yours if you want otherwise. A delivery has ten seconds, so hand slow work to a queue and return. The controller maps POST only, and mailkube activates an endpoint only after probing it with GET <url>?hub.mode=subscribe&hub.challenge=<token> and reading the token back. Map the probe yourself on the same path:
With Spring Security on the classpath, the endpoint is an unauthenticated POST verified by signature, so CSRF protection rejects it. The starter does not modify your SecurityFilterChain; widen it yourself:

Next steps

Java SDK

The client under the starter: the builder, scheduled sends, sealed events, and virtual-thread concurrency.

Webhooks

The catalog behind MailkubeWebhookEvent, with payloads, signing, and retries.