0
# Spring Boot Starter Mail
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: spring-boot-starter-mail
7
- **Package Type**: maven
8
- **Group ID**: org.springframework.boot
9
- **Language**: Java
10
- **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'`
11

12
## Core Imports
13

14
```java
15
import org.springframework.mail.MailSender;
16
import org.springframework.mail.javamail.JavaMailSender;
17
import org.springframework.mail.javamail.JavaMailSenderImpl;
18
import org.springframework.boot.autoconfigure.mail.MailProperties;
19
import org.springframework.mail.SimpleMailMessage;
20
import org.springframework.mail.javamail.MimeMessageHelper;
21
import org.springframework.mail.javamail.MimeMessagePreparator;
22
import jakarta.mail.MessagingException;
23
import java.io.InputStream;
24
```
25

26
## Basic Usage
27

28
```java
29
import org.springframework.beans.factory.annotation.Autowired;
30
import org.springframework.mail.SimpleMailMessage;
31
import org.springframework.mail.javamail.JavaMailSender;
32
import org.springframework.stereotype.Service;
33

34
@Service
35
public class EmailService {
36
    
37
    @Autowired
38
    private JavaMailSender mailSender;
39
    
40
    public void sendSimpleEmail(String to, String subject, String text) {
41
        SimpleMailMessage message = new SimpleMailMessage();
42
        message.setTo(to);
43
        message.setSubject(subject);
44
        message.setText(text);
45
        mailSender.send(message);
46
    }
47
}
48
```
49

50
Application properties configuration:
51
```properties
52
spring.mail.host=smtp.example.com
53
spring.mail.port=587
54
spring.mail.username=your-username
55
spring.mail.password=your-password
56
spring.mail.properties.mail.smtp.auth=true
57
spring.mail.properties.mail.smtp.starttls.enable=true
58
```
59

60
## Capabilities
61

62
### Auto-Configuration
63

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

66
```java { .api }
67
@AutoConfiguration
68
@ConditionalOnClass({MimeMessage.class, MimeType.class, MailSender.class})
69
@ConditionalOnMissingBean(MailSender.class)
70
@EnableConfigurationProperties(MailProperties.class)
71
public class MailSenderAutoConfiguration {
72
    // Auto-configuration for email support
73
}
74
```
75

76
The auto-configuration activates when:
77
- `spring.mail.host` property is set (for properties-based configuration)
78
- `spring.mail.jndi-name` property is set (for JNDI-based configuration)
79

80
### Mail Properties Configuration
81

82
Configuration properties for customizing email behavior.
83

84
```java { .api }
85
@ConfigurationProperties("spring.mail")
86
public class MailProperties {
87
    public String getHost();
88
    public void setHost(String host);
89
    
90
    public Integer getPort();  
91
    public void setPort(Integer port);
92
    
93
    public String getUsername();
94
    public void setUsername(String username);
95
    
96
    public String getPassword();
97
    public void setPassword(String password);
98
    
99
    public String getProtocol();
100
    public void setProtocol(String protocol);
101
    
102
    public Charset getDefaultEncoding();
103
    public void setDefaultEncoding(Charset defaultEncoding);
104
    
105
    public Map<String, String> getProperties();
106
    
107
    public String getJndiName();
108
    public void setJndiName(String jndiName);
109
    
110
    public Ssl getSsl();
111
}
112
```
113

114
### SSL Configuration
115

116
Nested SSL configuration within MailProperties.
117

118
```java { .api }
119
public static class Ssl {
120
    public boolean isEnabled();
121
    public void setEnabled(boolean enabled);
122
    
123
    public String getBundle();
124
    public void setBundle(String bundle);
125
}
126
```
127

128
### JavaMail Sender Bean
129

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

132
```java { .api }
133
@Bean
134
@ConditionalOnMissingBean(JavaMailSender.class)
135
JavaMailSenderImpl mailSender(MailProperties properties, ObjectProvider<SslBundles> sslBundles);
136
```
137

138
### Connection Validation
139

140
Optional connection testing on application startup.
141

142
```java { .api }
143
@AutoConfiguration(after = MailSenderAutoConfiguration.class)
144
@ConditionalOnBooleanProperty("spring.mail.test-connection")
145
public class MailSenderValidatorAutoConfiguration {
146
    public void validateConnection() throws IllegalStateException;
147
}
148
```
149

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

152
### Health Monitoring
153

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

156
```java { .api }
157
public class MailHealthIndicator extends AbstractHealthIndicator {
158
    public MailHealthIndicator(JavaMailSenderImpl mailSender);
159
    protected void doHealthCheck(Builder builder) throws Exception;
160
}
161

162
@AutoConfiguration(after = MailSenderAutoConfiguration.class)
163
@ConditionalOnClass(JavaMailSenderImpl.class)
164
@ConditionalOnBean(JavaMailSenderImpl.class)
165
@ConditionalOnEnabledHealthIndicator("mail")
166
public class MailHealthContributorAutoConfiguration {
167
    @Bean
168
    @ConditionalOnMissingBean(name = {"mailHealthIndicator", "mailHealthContributor"})
169
    public HealthContributor mailHealthContributor(ConfigurableListableBeanFactory beanFactory);
170
}
171
```
172

173
The health indicator is automatically registered when:
174
- Spring Boot Actuator is present
175
- JavaMailSenderImpl bean exists
176
- Mail health indicator is enabled (default: true)
177
- `@ConditionalOnEnabledHealthIndicator("mail")` condition is met
178

179
### JNDI Configuration
180

181
Alternative configuration using JNDI lookup for Jakarta Mail Session.
182

183
```java { .api }
184
@Configuration(proxyBeanMethods = false)
185
@ConditionalOnClass(Session.class)
186
@ConditionalOnProperty("spring.mail.jndi-name")
187
@ConditionalOnJndi
188
public class MailSenderJndiConfiguration {
189
    @Bean
190
    JavaMailSenderImpl mailSender(Session session);
191
    
192
    @Bean
193
    @ConditionalOnMissingBean
194
    Session session() throws IllegalStateException;
195
}
196
```
197

198
## Configuration Properties
199

200
### Core Mail Properties
201

202
| Property | Type | Default | Description |
203
|----------|------|---------|-------------|
204
| `spring.mail.host` | String | null | SMTP server host (e.g., 'smtp.example.com') |
205
| `spring.mail.port` | Integer | null | SMTP server port |
206
| `spring.mail.username` | String | null | Login user of the SMTP server |
207
| `spring.mail.password` | String | null | Login password of the SMTP server |
208
| `spring.mail.protocol` | String | "smtp" | Protocol used by the SMTP server |
209
| `spring.mail.default-encoding` | String | "UTF-8" | Default MimeMessage encoding |
210
| `spring.mail.jndi-name` | String | null | Session JNDI name (takes precedence) |
211
| `spring.mail.test-connection` | Boolean | false | Test connection on startup |
212
213
### SSL Properties
214

215
| Property | Type | Default | Description |
216
|----------|------|---------|-------------|
217
| `spring.mail.ssl.enabled` | Boolean | false | Enable SSL support |
218
| `spring.mail.ssl.bundle` | String | null | SSL bundle name for SSLSocketFactory |
219
220
### Additional JavaMail Properties
221

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

224
```properties
225
spring.mail.properties.mail.smtp.auth=true
226
spring.mail.properties.mail.smtp.starttls.enable=true
227
spring.mail.properties.mail.smtp.ssl.trust=smtp.example.com
228
```
229

230
## Usage Examples
231

232
### Sending Plain Text Email
233

234
```java
235
@Autowired
236
private JavaMailSender mailSender;
237

238
public void sendPlainTextEmail() {
239
    SimpleMailMessage message = new SimpleMailMessage();
240
    message.setFrom("sender@example.com");
241
    message.setTo("recipient@example.com");
242
    message.setSubject("Test Subject");
243
    message.setText("Hello, this is a test email!");
244
    
245
    mailSender.send(message);
246
}
247
```
248

249
### Sending HTML Email
250

251
```java
252
import jakarta.mail.MessagingException;
253
import jakarta.mail.internet.MimeMessage;
254
import org.springframework.mail.javamail.MimeMessageHelper;
255

256
@Autowired
257
private JavaMailSender mailSender;
258

259
public void sendHtmlEmail() throws MessagingException {
260
    MimeMessage message = mailSender.createMimeMessage();
261
    MimeMessageHelper helper = new MimeMessageHelper(message, true);
262
    
263
    helper.setFrom("sender@example.com");
264
    helper.setTo("recipient@example.com");
265
    helper.setSubject("HTML Email");
266
    helper.setText("<html><body><h1>Hello!</h1><p>This is an HTML email.</p></body></html>", true);
267
    
268
    mailSender.send(message);
269
}
270
```
271

272
### Using JNDI Configuration
273

274
When using JNDI, configure only the JNDI name:
275

276
```properties
277
spring.mail.jndi-name=java:comp/env/mail/Session
278
```
279

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

282
### Connection Testing
283

284
Enable connection testing to validate mail server configuration on startup:
285

286
```properties
287
spring.mail.test-connection=true
288
```
289

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

292
## Types
293

294
### Key Interfaces and Classes
295

296
```java { .api }
297
// Spring's mail sender interfaces
298
public interface MailSender {
299
    void send(SimpleMailMessage simpleMessage) throws MailException;
300
    void send(SimpleMailMessage... simpleMessages) throws MailException;
301
}
302

303
public interface JavaMailSender extends MailSender {
304
    MimeMessage createMimeMessage();
305
    MimeMessage createMimeMessage(InputStream contentStream) throws MailException;
306
    void send(MimeMessage mimeMessage) throws MailException;
307
    void send(MimeMessage... mimeMessages) throws MailException;
308
    void send(MimeMessagePreparator mimeMessagePreparator) throws MailException;
309
    void send(MimeMessagePreparator... mimeMessagePreparators) throws MailException;
310
}
311

312
// Message preparation callback interface
313
@FunctionalInterface
314
public interface MimeMessagePreparator {
315
    void prepare(MimeMessage mimeMessage) throws Exception;
316
}
317

318
// Implementation provided by auto-configuration  
319
public class JavaMailSenderImpl implements JavaMailSender {
320
    public void setHost(String host);
321
    public void setPort(int port);
322
    public void setUsername(String username);
323
    public void setPassword(String password);
324
    public void setProtocol(String protocol);
325
    public void setDefaultEncoding(String defaultEncoding);
326
    public void setJavaMailProperties(Properties javaMailProperties);
327
    public void setSession(Session session);
328
    public void testConnection() throws MessagingException;
329
}
330

331
// Simple message for plain text emails
332
public class SimpleMailMessage implements MailMessage, Serializable {
333
    public void setFrom(String from);
334
    public void setReplyTo(String replyTo);
335
    public void setTo(String to);
336
    public void setTo(String... to);
337
    public void setCc(String cc);
338
    public void setCc(String... cc);
339
    public void setBcc(String bcc);
340
    public void setBcc(String... bcc);
341
    public void setSentDate(Date sentDate);
342
    public void setSubject(String subject);
343
    public void setText(String text);
344
}
345
```
346

347
### Exception Types
348

349
```java { .api }
350
// Base exception for mail operations
351
public abstract class MailException extends RuntimeException {
352
    // Runtime exception for mail sending failures
353
}
354

355
// Specific mail exceptions
356
public class MailSendException extends MailException {
357
    // Exception thrown when mail sending fails
358
}
359

360
public class MailAuthenticationException extends MailException {
361
    // Exception thrown when mail authentication fails  
362
}
363

364
public class MailPreparationException extends MailException {
365
    // Exception thrown when mail preparation fails
366
}
367
```
368

369
## Dependencies
370

371
The starter automatically includes:
372

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

377
Optional dependencies:
378
- `org.springframework.boot:spring-boot-starter-actuator` - Enables health monitoring
379
- SSL bundles support through Spring Boot's SSL configuration