or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-org-springframework-boot--spring-boot-starter-mail

Starter for using Java Mail and Spring Framework's email sending support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.springframework.boot/spring-boot-starter-mail@3.5.x

To install, run

npx @tessl/cli install tessl/maven-org-springframework-boot--spring-boot-starter-mail@3.5.0

index.mddocs/

Spring Boot Starter Mail

Spring Boot Starter Mail provides auto-configuration for email functionality using Java Mail and Spring Framework's email sending support. It automatically configures JavaMail support, SMTP servers, mail properties, and mail sender components with minimal configuration.

Package Information

  • Package Name: spring-boot-starter-mail
  • Package Type: maven
  • Group ID: org.springframework.boot
  • Language: Java
  • Installation: Add to Maven: <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-mail</artifactId></dependency> or Gradle: implementation 'org.springframework.boot:spring-boot-starter-mail'

Core Imports

import org.springframework.mail.MailSender;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.mail.javamail.JavaMailSenderImpl;
import org.springframework.boot.autoconfigure.mail.MailProperties;
import org.springframework.mail.SimpleMailMessage;
import org.springframework.mail.javamail.MimeMessageHelper;
import org.springframework.mail.javamail.MimeMessagePreparator;
import jakarta.mail.MessagingException;
import java.io.InputStream;

Basic Usage

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.mail.SimpleMailMessage;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.stereotype.Service;

@Service
public class EmailService {
    
    @Autowired
    private JavaMailSender mailSender;
    
    public void sendSimpleEmail(String to, String subject, String text) {
        SimpleMailMessage message = new SimpleMailMessage();
        message.setTo(to);
        message.setSubject(subject);
        message.setText(text);
        mailSender.send(message);
    }
}

Application properties configuration:

spring.mail.host=smtp.example.com
spring.mail.port=587
spring.mail.username=your-username
spring.mail.password=your-password
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true

Capabilities

Auto-Configuration

Spring Boot automatically configures mail support when the starter is present.

@AutoConfiguration
@ConditionalOnClass({MimeMessage.class, MimeType.class, MailSender.class})
@ConditionalOnMissingBean(MailSender.class)
@EnableConfigurationProperties(MailProperties.class)
public class MailSenderAutoConfiguration {
    // Auto-configuration for email support
}

The auto-configuration activates when:

  • spring.mail.host property is set (for properties-based configuration)
  • spring.mail.jndi-name property is set (for JNDI-based configuration)

Mail Properties Configuration

Configuration properties for customizing email behavior.

@ConfigurationProperties("spring.mail")
public class MailProperties {
    public String getHost();
    public void setHost(String host);
    
    public Integer getPort();  
    public void setPort(Integer port);
    
    public String getUsername();
    public void setUsername(String username);
    
    public String getPassword();
    public void setPassword(String password);
    
    public String getProtocol();
    public void setProtocol(String protocol);
    
    public Charset getDefaultEncoding();
    public void setDefaultEncoding(Charset defaultEncoding);
    
    public Map<String, String> getProperties();
    
    public String getJndiName();
    public void setJndiName(String jndiName);
    
    public Ssl getSsl();
}

SSL Configuration

Nested SSL configuration within MailProperties.

public static class Ssl {
    public boolean isEnabled();
    public void setEnabled(boolean enabled);
    
    public String getBundle();
    public void setBundle(String bundle);
}

JavaMail Sender Bean

The primary bean for sending emails, automatically configured by Spring Boot.

@Bean
@ConditionalOnMissingBean(JavaMailSender.class)
JavaMailSenderImpl mailSender(MailProperties properties, ObjectProvider<SslBundles> sslBundles);

Connection Validation

Optional connection testing on application startup.

@AutoConfiguration(after = MailSenderAutoConfiguration.class)
@ConditionalOnBooleanProperty("spring.mail.test-connection")
public class MailSenderValidatorAutoConfiguration {
    public void validateConnection() throws IllegalStateException;
}

Activated when spring.mail.test-connection=true is set.

Health Monitoring

Health indicator for monitoring mail server connectivity (requires Spring Boot Actuator).

public class MailHealthIndicator extends AbstractHealthIndicator {
    public MailHealthIndicator(JavaMailSenderImpl mailSender);
    protected void doHealthCheck(Builder builder) throws Exception;
}

@AutoConfiguration(after = MailSenderAutoConfiguration.class)
@ConditionalOnClass(JavaMailSenderImpl.class)
@ConditionalOnBean(JavaMailSenderImpl.class)
@ConditionalOnEnabledHealthIndicator("mail")
public class MailHealthContributorAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean(name = {"mailHealthIndicator", "mailHealthContributor"})
    public HealthContributor mailHealthContributor(ConfigurableListableBeanFactory beanFactory);
}

The health indicator is automatically registered when:

  • Spring Boot Actuator is present
  • JavaMailSenderImpl bean exists
  • Mail health indicator is enabled (default: true)
  • @ConditionalOnEnabledHealthIndicator("mail") condition is met

JNDI Configuration

Alternative configuration using JNDI lookup for Jakarta Mail Session.

@Configuration(proxyBeanMethods = false)
@ConditionalOnClass(Session.class)
@ConditionalOnProperty("spring.mail.jndi-name")
@ConditionalOnJndi
public class MailSenderJndiConfiguration {
    @Bean
    JavaMailSenderImpl mailSender(Session session);
    
    @Bean
    @ConditionalOnMissingBean
    Session session() throws IllegalStateException;
}

Configuration Properties

Core Mail Properties

PropertyTypeDefaultDescription
spring.mail.hostStringnullSMTP server host (e.g., 'smtp.example.com')
spring.mail.portIntegernullSMTP server port
spring.mail.usernameStringnullLogin user of the SMTP server
spring.mail.passwordStringnullLogin password of the SMTP server
spring.mail.protocolString"smtp"Protocol used by the SMTP server
spring.mail.default-encodingString"UTF-8"Default MimeMessage encoding
spring.mail.jndi-nameStringnullSession JNDI name (takes precedence)
spring.mail.test-connectionBooleanfalseTest connection on startup

SSL Properties

PropertyTypeDefaultDescription
spring.mail.ssl.enabledBooleanfalseEnable SSL support
spring.mail.ssl.bundleStringnullSSL bundle name for SSLSocketFactory

Additional JavaMail Properties

Additional properties can be set using the spring.mail.properties.* prefix:

spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.ssl.trust=smtp.example.com

Usage Examples

Sending Plain Text Email

@Autowired
private JavaMailSender mailSender;

public void sendPlainTextEmail() {
    SimpleMailMessage message = new SimpleMailMessage();
    message.setFrom("sender@example.com");
    message.setTo("recipient@example.com");
    message.setSubject("Test Subject");
    message.setText("Hello, this is a test email!");
    
    mailSender.send(message);
}

Sending HTML Email

import jakarta.mail.MessagingException;
import jakarta.mail.internet.MimeMessage;
import org.springframework.mail.javamail.MimeMessageHelper;

@Autowired
private JavaMailSender mailSender;

public void sendHtmlEmail() throws MessagingException {
    MimeMessage message = mailSender.createMimeMessage();
    MimeMessageHelper helper = new MimeMessageHelper(message, true);
    
    helper.setFrom("sender@example.com");
    helper.setTo("recipient@example.com");
    helper.setSubject("HTML Email");
    helper.setText("<html><body><h1>Hello!</h1><p>This is an HTML email.</p></body></html>", true);
    
    mailSender.send(message);
}

Using JNDI Configuration

When using JNDI, configure only the JNDI name:

spring.mail.jndi-name=java:comp/env/mail/Session

The JavaMail Session will be looked up from JNDI instead of being created from properties.

Connection Testing

Enable connection testing to validate mail server configuration on startup:

spring.mail.test-connection=true

If the connection fails, the application will fail to start with an IllegalStateException.

Types

Key Interfaces and Classes

// Spring's mail sender interfaces
public interface MailSender {
    void send(SimpleMailMessage simpleMessage) throws MailException;
    void send(SimpleMailMessage... simpleMessages) throws MailException;
}

public interface JavaMailSender extends MailSender {
    MimeMessage createMimeMessage();
    MimeMessage createMimeMessage(InputStream contentStream) throws MailException;
    void send(MimeMessage mimeMessage) throws MailException;
    void send(MimeMessage... mimeMessages) throws MailException;
    void send(MimeMessagePreparator mimeMessagePreparator) throws MailException;
    void send(MimeMessagePreparator... mimeMessagePreparators) throws MailException;
}

// Message preparation callback interface
@FunctionalInterface
public interface MimeMessagePreparator {
    void prepare(MimeMessage mimeMessage) throws Exception;
}

// Implementation provided by auto-configuration  
public class JavaMailSenderImpl implements JavaMailSender {
    public void setHost(String host);
    public void setPort(int port);
    public void setUsername(String username);
    public void setPassword(String password);
    public void setProtocol(String protocol);
    public void setDefaultEncoding(String defaultEncoding);
    public void setJavaMailProperties(Properties javaMailProperties);
    public void setSession(Session session);
    public void testConnection() throws MessagingException;
}

// Simple message for plain text emails
public class SimpleMailMessage implements MailMessage, Serializable {
    public void setFrom(String from);
    public void setReplyTo(String replyTo);
    public void setTo(String to);
    public void setTo(String... to);
    public void setCc(String cc);
    public void setCc(String... cc);
    public void setBcc(String bcc);
    public void setBcc(String... bcc);
    public void setSentDate(Date sentDate);
    public void setSubject(String subject);
    public void setText(String text);
}

Exception Types

// Base exception for mail operations
public abstract class MailException extends RuntimeException {
    // Runtime exception for mail sending failures
}

// Specific mail exceptions
public class MailSendException extends MailException {
    // Exception thrown when mail sending fails
}

public class MailAuthenticationException extends MailException {
    // Exception thrown when mail authentication fails  
}

public class MailPreparationException extends MailException {
    // Exception thrown when mail preparation fails
}

Dependencies

The starter automatically includes:

  • org.springframework.boot:spring-boot-starter - Base Spring Boot functionality
  • org.springframework:spring-context-support - Spring context support including email
  • org.eclipse.angus:jakarta.mail - Jakarta Mail API implementation

Optional dependencies:

  • org.springframework.boot:spring-boot-starter-actuator - Enables health monitoring
  • SSL bundles support through Spring Boot's SSL configuration