Spring Boot – Sending Email

<!-- Adding this starter alone changes nothing at runtime: Boot's mail
     autoconfiguration only builds a JavaMailSender when spring.mail.host is set,
     which it is not by default. See MailService for how that is handled. -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mail</artifactId>
</dependency>

# NO spring.mail.host by default, and that is the switch: without it Boot builds no
# JavaMailSender at all and MailService quietly does nothing. To actually send, run a
# local sink and point at it - MailHog or Mailpit both work:
#   docker run -p 1025:1025 -p 8025:8025 axllent/mailpit
#   ./mvnw spring-boot:run -Dspring-boot.run.arguments=--spring.mail.host=localhost,--spring.mail.port=1025
# then read what was "sent" at http://localhost:8025. Never point a demo at a real
# SMTP relay - the first bad test address is a bounce on somebody's real domain.
pizza.mail.from=orders@pizza.test

/**
 * Outgoing mail.
 *
 * <p>Only the envelope sender lives here — the SMTP host, port and credentials are Boot's own
 * {@code spring.mail.*} properties, and duplicating them under {@code pizza.*} would just give
 * the two copies a chance to disagree. Bind your own settings, not the framework's.
 */
public record Mail(@NotBlank String from) {}

/**
 * <h2>Why {@link ObjectProvider} instead of injecting {@link JavaMailSender} directly</h2>
 *
 * <p>Boot only creates a {@code JavaMailSender} when {@code spring.mail.host} is set. Injecting it
 * as a normal required dependency would therefore make the entire application fail to start on any
 * machine without mail configured — which, for a demo somebody just cloned, is a terrible first
 * experience.
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class MailServiceImpl implements MailService {

    private final ObjectProvider<JavaMailSender> mailSenderProvider;
    private final TemplateEngine templateEngine;
    private final PizzaProperties properties;

    @Override
    public boolean isConfigured() {
        return mailSenderProvider.getIfAvailable() != null;
    }
}

@Override
public void sendOrderConfirmation(OrderDTO order) {
    JavaMailSender sender = mailSenderProvider.getIfAvailable();
    if (sender == null) {
        log.debug("No mail server configured — skipping the confirmation for order {}", order.id());
        return;
    }
    if (order.email() == null || order.email().isBlank()) {
        log.warn("Order {} has no email address — nothing to send to", order.id());
        return;
    }

    try {
        Context context = new Context();
        context.setVariable("order", order);
        String html = templateEngine.process("receipt", context);

        MimeMessage message = sender.createMimeMessage();
        // multipart=true is required to attach anything; the charset must be stated or a
        // customer named Zoë gets mojibake in the subject line.
        MimeMessageHelper helper =
                new MimeMessageHelper(message, true, StandardCharsets.UTF_8.name());

        helper.setFrom(properties.mail().from());
        helper.setTo(order.email());
        helper.setSubject("Your Pizza order " + order.id());
        // The second argument is what makes this HTML rather than a wall of angle brackets.
        // A production sender would pass a plain-text alternative as the first argument, for
        // clients that refuse HTML.
        helper.setText(html, true);

        sender.send(message);
        log.info("Confirmation for order {} sent to {}", order.id(), order.email());

    } catch (Exception ex) {
        log.error("Could not send the confirmation for order {} — the order is unaffected",
                order.id(), ex);
    }
}

SimpleMailMessage message = new SimpleMailMessage();
message.setFrom(properties.mail().from());
message.setTo(order.email());
message.setSubject("Your order is on its way");
message.setText("Order " + order.id() + " has left the kitchen.");
sender.send(message);

// The Context is the model. Thymeleaf has no idea it is producing an email; it sees the
// same variable name the receipt page sets, which is why one template serves both.
Context context = new Context();
context.setVariable("order", order);
String html = templateEngine.process("receipt", context);

@Async
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void sendConfirmation(OrderPlacedEvent event) {
    try {
        mailService.sendOrderConfirmation(
                orderService.getOrderByPublicId(event.orderPublicId()));
    } catch (Exception ex) {
        log.error("Confirmation for order {} failed — the order itself is unaffected",
                event.orderPublicId(), ex);
    }
}

// Swallowed on purpose, and logged loudly. This is called from an AFTER_COMMIT
// listener: the order exists and is paid for. Letting a mail failure propagate would
// achieve nothing except noise, since there is no transaction left to roll back.

# 1. As plain SMTP — no code changes at all
spring.mail.host=email-smtp.us-west-2.amazonaws.com
spring.mail.port=587
spring.mail.username=${SMTP_USERNAME}
spring.mail.password=${SMTP_PASSWORD}
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true

@SpringBootTest
class MailServiceTest {

    @MockitoBean
    private JavaMailSender mailSender;

    @Autowired
    private MailService mailService;

    @Test
    void sendsHtmlConfirmationToTheCustomer() {
        given(mailSender.createMimeMessage())
                .willReturn(new JavaMailSenderImpl().createMimeMessage());

        mailService.sendOrderConfirmation(anOrder("customer@pizza.test"));

        then(mailSender).should().send(any(MimeMessage.class));
    }
}