Send email with Spring Boot

# src/main/resources/application.properties
spring.mail.host=smtp.poststack.dev
spring.mail.port=587
spring.mail.username=poststack
spring.mail.password=${POSTSTACK_API_KEY}
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true
spring.mail.properties.mail.smtp.connectiontimeout=5000
spring.mail.properties.mail.smtp.timeout=10000
spring.mail.properties.mail.smtp.writetimeout=10000

# Port 465 instead: spring.mail.port=465 and
# spring.mail.properties.mail.smtp.ssl.enable=true (drop the starttls lines)

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

@Service
public class MailService {
    private final JavaMailSender mailSender;

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

    public void sendWelcome(String to, String name) throws MessagingException {
        MimeMessage message = mailSender.createMimeMessage();
        MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");

        helper.setFrom("hello@yourdomain.com");   // must be on a verified domain
        helper.setTo(to);
        helper.setSubject("Welcome to Acme");
        helper.setText(
            "Welcome, " + name + "!",                       // plain-text part
            "<h1>Welcome, " + name + "!</h1>"               // HTML part
        );
        message.addHeader("X-PostStack-Tags", "welcome,onboarding");

        mailSender.send(message);
    }
}

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.mail.MailAuthenticationException;
import org.springframework.mail.MailSendException;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Recover;
import org.springframework.retry.annotation.Retryable;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;

// Needs @EnableAsync and @EnableRetry on a @Configuration class,
// plus org.springframework.retry:spring-retry and spring-boot-starter-aop.
@Service
public class WelcomeMailer {
    private static final Logger log = LoggerFactory.getLogger(WelcomeMailer.class);
    private final MailService mail;

    public WelcomeMailer(MailService mail) {
        this.mail = mail;
    }

    @Async
    @Retryable(
        retryFor = MailSendException.class,                 // timeouts, 4xx temporary replies
        noRetryFor = MailAuthenticationException.class,     // 535: bad API key, retrying won't help
        maxAttempts = 4,
        backoff = @Backoff(delay = 30_000, multiplier = 2))
    public void send(String to, String name) throws Exception {
        mail.sendWelcome(to, name);
    }

    @Recover
    public void giveUp(Exception e, String to, String name) {
        // 550 = permanent rejection, e.g. the From domain is not verified
        log.error("PostStack could not send the welcome email to {}: {}", to, e.getMessage());
    }
}

MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");

helper.setFrom("billing@yourdomain.com");
helper.setTo(order.getEmail());
helper.setReplyTo("support@yourdomain.com");
helper.setSubject("Invoice #" + order.getNumber());
helper.setText(
    "Your invoice is attached.",
    "<p>Your invoice is attached.</p><img src='cid:logo'>");

helper.addInline("logo", new ClassPathResource("static/logo.png"));
helper.addAttachment("invoice-" + order.getNumber() + ".pdf",
    new ByteArrayResource(order.getInvoicePdf()), "application/pdf");

message.addHeader("X-PostStack-Idempotency-Key", "invoice-" + order.getId());

mailSender.send(message);

import java.util.List;
import java.util.Map;
import java.util.UUID;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

@Service
public class PostStackApi {
    record SendResponse(String id) {}

    private final RestClient client;

    public PostStackApi(@Value("${poststack.api-key}") String apiKey) {
        this.client = RestClient.builder()
            .baseUrl("https://api.poststack.dev")
            .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + apiKey)
            .build();
    }

    public String sendWelcome(String to) {
        return client.post()
            .uri("/emails")
            .contentType(MediaType.APPLICATION_JSON)
            .header("Idempotency-Key", UUID.randomUUID().toString()) // reuse it on retry
            .body(Map.of(
                "from", "Acme <hello@yourdomain.com>",
                "to", List.of(to),
                "subject", "Welcome to Acme",
                "html", "<h1>Welcome!</h1>",
                "tags", List.of("welcome")))
            .retrieve()   // throws RestClientResponseException on 4xx/5xx
            .body(SendResponse.class)
            .id();
    }
}

// application.properties: poststack.api-key=${POSTSTACK_API_KEY}

Context ctx = new Context(Locale.ENGLISH);
ctx.setVariable("name", user.getName());
String html = templateEngine.process("mail/welcome", ctx);  // templates/mail/welcome.html

helper.setText("Welcome, " + user.getName() + "!", html);