MailKite Spring Boot Starter

Email for every product you ship — send over a verified domain, receive email as a webhook, give an AI agent its own inbox.
The official MailKite auto-configuration for Spring Boot: set two properties, get a MailSender/JavaMailSender bean.

Docs · Spring Boot guide · mailkite.dev · AI agents

Read-only mirror. This repo is a generated, release-time mirror of the MailKite monorepo (the private source of truth) — development doesn't happen here. Install from Maven Central and open issues against the MailKite docs.

Install

Maven (pom.xml):

<dependency>
  <groupId>dev.mailkite</groupId>
  <artifactId>mailkite-spring-boot-starter</artifactId>
  <version>0.1.0</version>
</dependency>

Gradle (build.gradle/build.gradle.kts):

implementation "dev.mailkite:mailkite-spring-boot-starter:0.1.0"

Requires Java 17+ and Spring Boot 3.x.

Configure

Add your API key to application.properties (create one in the dashboard):

mailkite.api-key=${MAILKITE_API_KEY}

or application.yml:

mailkite:
  api-key: ${MAILKITE_API_KEY}

Setting the MAILKITE_API_KEY environment variable is enough on its own — Spring Boot's relaxed property binding maps it onto mailkite.api-key automatically, no properties file entry required.

That's it. Auto-configuration registers a MailKiteMailSender bean (implements both org.springframework.mail.MailSender and org.springframework.mail.javamail.JavaMailSender) the moment mailkite.api-key is present, and backs off if your app already defines its own MailSender/JavaMailSender (e.g. spring-boot-starter-mail's SMTP-based one) — adding this starter never silently overrides an existing mail setup.

Send

Autowire JavaMailSender (or the narrower MailSender) like you would with any Spring mail setup — no MailKite-specific types in your code:

@Service
public class NotificationService {

  private final JavaMailSender mailSender;

  public NotificationService(JavaMailSender mailSender) {
    this.mailSender = mailSender;
  }

  public void sendWelcome(String to) {
    SimpleMailMessage message = new SimpleMailMessage();
    message.setFrom("hello@yourdomain.com");
    message.setTo(to);
    message.setSubject("Welcome!");
    message.setText("Thanks for signing up.");
    mailSender.send(message);
  }
}

HTML mail with an attachment, using Spring's MimeMessageHelper:

MimeMessage mime = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(mime, true);
helper.setFrom("hello@yourdomain.com");
helper.setTo("ada@example.com");
helper.setSubject("Your invoice");
helper.setText("<p>Thanks for your order!</p>", true);
helper.addAttachment("invoice.pdf", new ByteArrayResource(invoicePdfBytes));
mailSender.send(mime);

The from domain must be verified (SPF + DKIM) on your MailKite account.

What maps where

Spring mail	MailKite send	Notes
from (or mailkite.default-from if unset)	from	required — one address
to / cc / bcc	to / cc / bcc	arrays; cc/bcc omitted when empty
subject	subject
text / HTML body	text / html	multipart/alternative keeps both
Reply-To	replyTo	single address only — 2+ throws MailParseException
In-Reply-To header	inReplyTo	threading
attachments	attachments[]	base64 content + filename + contentType

Honest failures, not silent drops. The MailKite send API carries a fixed envelope, so MailKiteMailSender throws Spring's own MailParseException/MailSendException (wrapping the API's error message) instead of pretending:

• API errors (unverified domain, suppressed recipient, rate limit, …) surface as MailSendException with the underlying MailKiteException (.status + .body).
• Custom headers beyond the mapped set are refused — the API can't deliver them.
• Inline (cid:-embedded) images are refused — host the image at a URL instead.
• Multiple reply-to addresses are refused — the API takes one.

Configuration reference

Property	Env var	Required	Default	Description
mailkite.api-key	MAILKITE_API_KEY	✓	—	Enables auto-configuration when set.
mailkite.base-url	MAILKITE_BASE_URL		https://api.mailkite.dev	Override for self-hosted/staging.
mailkite.default-from	MAILKITE_DEFAULT_FROM		—	Used when a message doesn't set a from address.

Runnable example

A full Spring Boot web app with a form + controller using MailKiteMailSender lives at starters/spring-boot in the monorepo — see its README for mvn spring-boot:run instructions.

All MailKite libraries

Same contract, every language (full list: https://mailkite.dev/docs/libraries):

Library	Repo	Distribution
MailKite Spring Boot Starter (this repo)	spring-boot-starter	Maven Central
MailKite for Java	mailkite-java	Maven Central
MailKite for Laravel	laravel	Packagist
MailKite for PHP	mailkite-php	Packagist
MailKite for Node.js	mailkite-node	npm
MailKite for Python	mailkite-python	PyPI
MailKite for Ruby	mailkite-ruby	RubyGems
MailKite for Go	mailkite-go	Go modules
@mailkite/cli	mailkite-cli	npm
@mailkite/mcp	mailkite-mcp	npm

Docs & links

• 📚 Documentation: https://mailkite.dev/docs
• 📦 This library's guide: https://mailkite.dev/docs/integrations/spring-boot
• 🤖 AI agents (MCP + inbox agents): https://mailkite.dev/docs/ai-agents
• 🌐 Website: https://mailkite.dev

_{MIT licensed. © MailKite.}