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
ReplaceX.Y.Z with the current version on Maven Central.
MAILKUBE_API_KEY from the environment.
Send
Inject Spring’sMailSender 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:
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 ownMailException 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:@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:
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.