Spring Boot Mastery: From Basics to Advanced

Chapter: Send Email Using Spring Boot | Gmail SMTP | Java Mail Sender

Automating transactional and notification emails is a fundamental requirement in modern backend applications. Spring Boot simplifies email infrastructure through its spring-boot-starter-mail dependency, automatically configuring a JavaMailSender bean based on externalized properties in application.yml. This note provides an end-to-end guide on configuring Gmail SMTP with App Passwords, encapsulating messaging logic within a dedicated service component, and testing email delivery.

1. Context and Problem Statement: Why Programmatic Emailing?

In real-world business domains, systems often query database records matching specific business rules—such as targeting users with valid email addresses and specific sentiment flags—and dispatch personalized email notifications.

Rather than interacting directly with raw TCP sockets or low-level SMTP APIs, Spring Boot abstracts email dispatching through the JavaMailSender interface. To implement this cleanly, we build an isolated EmailService component inside our service package, decoupling business triggers from messaging mechanics.

2. Architecture of Spring Email Integration: JavaMailSender & Auto-Configuration

Spring Boot uses auto-configuration mechanics for email services similar to how it handles database templates (such as MongoTemplate).

Key Components

1. JavaMailSender Interface: The core contract in Spring Framework (org.springframework.mail.javamail.JavaMailSender) for sending MIME and standard simple text emails.
2. SimpleMailMessage Class: A standard data holder used to construct basic plaintext emails (containing to, from, subject, and text fields).
3. Auto-Configuration Trigger: If spring-boot-starter-mail is present on the classpath AND valid SMTP configuration properties are provided, Spring Boot automatically creates and injects a JavaMailSenderImpl bean into your services.

Note: If you attempt to @Autowired JavaMailSender without configuring spring.mail.* properties in application.yml, the context will fail to start or the reference will remain uninitialized (null), resulting in injection errors.

3. Project Setup: Maven Dependency Configuration

To enable email functionality, add the spring-boot-starter-mail dependency to your project's pom.xml.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mail</artifactId>
</dependency>

After adding this dependency, reload your Maven project. This pulls in jakarta.mail and Spring's email abstraction libraries into your application classpath.

4. Configuring Gmail SMTP Properties (application.yml)

Spring Boot auto-configuration relies on properties under the spring.mail prefix inside application.yml or application.properties.

spring:
  mail:
    host: smtp.gmail.com
    port: 587
    username: your-actual-email@gmail.com
    password: your-16-digit-app-password
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true

Externalized SMTP Host Profiles

Depending on your email vendor, the SMTP host address and default secure ports differ:

5. Gmail App Passwords: Setup, Security Context, and 2FA Bypass

When using personal Gmail accounts for development or testing, standard account passwords cannot be used to authenticate with SMTP servers due to Google security policies.

Step-by-Step App Password Generation Workflow

1. Navigate to your Google Account Settings (myaccount.google.com).
2. Select Security from the left navigation panel.
3. Under How you sign in to Google, ensure 2-Step Verification is turned ON.
4. Search for or navigate to App Passwords.
5. Input a custom app identifier name (e.g., Java Mail or Spring Boot App).
6. Click Create to obtain a unique 16-character string (e.g., abcd efgh ijkl mnop).
7. Copy this string (without spaces) directly into your spring.mail.password application configuration.

Security Warning: App passwords bypass Two-Factor Authentication (2FA) for programmatic access. Never check raw app passwords or personal email credentials into public version control repositories (e.g., GitHub). Use environment variables (${SPRING_MAIL_PASSWORD}) in production systems.

6. Deep-Dive into Essential SMTP Properties & Port Options

To establish secure socket connections, the underlying JavaMail framework requires explicit flags passed via spring.mail.properties.*.

Property Breakdown

spring:
  mail:
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true

• mail.smtp.auth = true: Dictates whether the remote SMTP server requires credentials (username and password) for authentication before accepting outbound messages.
  • When false: Used primarily in local corporate relay servers or internal networks where IP address whitelisting is enforced instead of explicit credentials.
• mail.smtp.starttls.enable = true: Forces the connection to upgrade from an unencrypted standard TCP connection to a secure TLS (Transport Layer Security) encrypted stream using the STARTTLS command.

SMTP Port Comparison

• Port 25: The traditional SMTP port. Typically unencrypted, highly vulnerable to packet sniffing, and blocked by default by most modern Internet Service Providers (ISPs) and cloud providers (e.g., AWS, GCP).
• Port 587: The modern standard port for explicit email submission over TLS via STARTTLS. Data exchange transitions securely from cleartext to encrypted mode.
• Port 465: Historically used for implicit SSL wrapping (SMTPS).

7. Building the EmailService Component

We design an EmailService Spring @Service component responsible for encapsulating email message construction and execution handling.

package com.example.service;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.mail.SimpleMailMessage;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.stereotype.Service;
import lombok.extern.slf4j.Slf4j;

@Service
@Slf4j
public class EmailService {

    @Autowired
    private JavaMailSender javaMailSender;

    /**
     * Constructs and sends a simple text email.
     * 
     * @param to      Recipient's target email address
     * @param subject Subject line of the email
     * @param body    Plain text body content of the email
     */
    public void sendEmail(String to, String subject, String body) {
        try {
            SimpleMailMessage mail = new SimpleMailMessage();
            mail.setTo(to);
            mail.setSubject(subject);
            mail.setText(body);

            javaMailSender.send(mail);
            log.info("Email successfully sent to: {}", to);
        } catch (Exception e) {
            log.error("Exception occurred while sending email to {}: ", to, e);
        }
    }
}

Component Breakdown

1. @Service Annotation: Marks EmailService as a Spring-managed component eligible for dependency injection.
2. @Slf4j (Lombok): Provides a pre-configured log object to record execution output and diagnostic stack traces cleanly.
3. SimpleMailMessage Instantiation: Standard object initialized to wrap messaging metadata (setTo, setSubject, setText).
4. Try-Catch Encapsulation: Guarantees that any unexpected network timeouts or invalid email addresses are caught, logged, and prevented from causing application crashes.

8. Vertical Message Execution Flow

The sequence of actions involved when EmailService.sendEmail() is invoked is illustrated below:

EmailService.sendEmail(to, subject, body)
   |
   | 1. Instantiate SimpleMailMessage
   v
SimpleMailMessage
   |
   | 2. Populate fields (To, Subject, Text)
   v
javaMailSender.send(mail)
   |
   | 3. Establish TCP Connection (Port 587)
   v
Gmail SMTP Server (smtp.gmail.com)
   |
   | 4. Issue STARTTLS & Authenticate via App Password
   v
TLS Encrypted Communication Socket
   |
   | 5. Forward Message across Email Infrastructure
   v
Recipient Inbox

9. Testing and Verifying Email Execution

To verify that our configuration works without starting the full HTTP web server layer, we can write an integration test using standard Spring Boot testing patterns.

package com.example.service;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
public class EmailServiceTests {

    @Autowired
    private EmailService emailService;

    @Test
    public void testSendEmail() {
        String recipient = "test.recipient@example.com";
        String subject = "Testing Java Mail Sender";
        String body = "Hi, how are you? This is a test email sent from Spring Boot!";

        emailService.sendEmail(recipient, subject, body);
    }
}

Debugging Common Issues

• AuthenticationFailedException: Indicates an incorrect username or invalid/revoked 16-character Google App Password.
• MailConnectException / Connection Timeout: Typically indicates that port 587 is blocked by a local firewall, VPN, or corporate network proxy.
• NullPointerException on javaMailSender: Occurs when running standalone Java tests without bootstrapping the Spring Context (@SpringBootTest).

10. Production Realities: Personal SMTP vs. Enterprise Delivery Platforms

While personal Gmail SMTP accounts are suitable for rapid development, testing, and small personal projects, enterprise applications require dedicated messaging pipelines.

11. Summary and Key Takeaways

• Spring Boot Starter Abstraction: Adding spring-boot-starter-mail automatically configures the JavaMailSender bean based on spring.mail.* application properties.
• Gmail SMTP Configuration: Requires setting smtp.gmail.com as host and port 587 for secure TLS transport.
• App Password Requirement: Personal Gmail accounts require enabling 2-Step Verification (2FA) and generating a dedicated 16-character App Password to authenticate programmatically over SMTP.
• Security Properties: Enforce safe encrypted transfers by setting mail.smtp.auth=true and mail.smtp.starttls.enable=true.
• Simple Message Standard: Use SimpleMailMessage for plain text email payloads, configuring setTo(), setSubject(), and setText() methods.
• Graceful Error Handling: Wrap javaMailSender.send() inside robust try-catch blocks and log failures via @Slf4j to prevent application crashes during network outages.
• Production Transition: Gmail SMTP is ideal for localized prototyping and testing; production systems should transition to dedicated enterprise APIs (such as SendGrid or AWS SES) for scalability, analytics, and deliverability.