E-Mail-Versand in Spring Boot: 8 Lösungen, damit E-Mails nicht verloren gehen

Aktualisiert:
✦ KI zu diesem Artikel befragen
E-Mail-Versand in Spring Boot: 8 Lösungen, damit E-Mails nicht verloren gehen

📮 Kurz gesagt: Das Versenden von E-Mails in Spring Boot kann in 10 Minuten eingerichtet werden. Sicherzustellen, dass E-Mails nicht verloren gehen, nicht dupliziert werden, den Benutzer nicht blockieren und nicht von einem einzelnen Anbieter abhängen, ist eine separate Aufgabe. Ich untersuche 8 Lösungen anhand von Beispielen aus meinem Blog: Was zu tun ist, warum genau so und was das in der Praxis bringt.

📬 Haben Sie sich noch nicht für einen Anbieter entschieden? Beginnen Sie mit einem Überblick über 7 Dienste zum Versenden von E-Mails: Preise, Limits und wann welcher zu wählen ist und einem Vergleich von Resend vs. SendGrid.

⚡ Das Wichtigste in 30 Sekunden

  • ✅ SMTP – wenn die Unabhängigkeit vom Anbieter wichtig ist, HTTP API – wenn Idempotenz, Tags und Batch-Versand benötigt werden.
  • ✅ Der Geschäftslogikcode sollte den Anbieter nicht kennen: Schnittstelle + Implementierungen, die über @ConditionalOnProperty umgeschaltet werden.
  • ✅ E-Mail-Vorlagen – auf Ihrer Seite (Thymeleaf), damit ein Umzug zu einem anderen Anbieter nicht die Neufassung von Vorlagen bedeutet.
  • ✅ E-Mail – asynchron und nach dem Commit der Transaktion, nicht innerhalb davon.
  • ✅ Wiederholen Sie nur temporäre Fehler (429, 5xx) und mit einem Idempotenzschlüssel.

📑 Inhalt des Artikels:

⚖️ SMTP oder HTTP API

Die meisten Dienste (Resend, SendGrid, Mailgun, Postmark) bieten beide Möglichkeiten. Die Wahl zwischen ihnen ist eine Wahl zwischen Flexibilität und Funktionalität.

SMTP (JavaMailSender) HTTP API (SDK)
Anbieterwechsel Änderung von Host und Passwort in der Konfiguration Neue Implementierung im Code
Abhängigkeiten spring-boot-starter-mail Anbieterspezifisches SDK
Idempotenz, Tags, Batch Teilweise, über benutzerdefinierte Header Ja, "out of the box"
Antwort "Vom Server akzeptiert" E-Mail-ID, mit der weitergearbeitet werden kann
Wann zu wählen Einfaches Projekt, wenige Anbieter, Legacy Newsletter, zuverlässige Wiederholungen, Webhooks

In meinem Blog verwende ich die HTTP API von Resend über das Java SDK: Ich benötige E-Mail-IDs und Lieferanalysen. Aber für ein kleines Projekt ist SMTP eine durchaus normale Wahl.

📨 SMTP über JavaMailSender

Was es ist. Der Standardweg für Java, E-Mails zu versenden: Spring Boot konfiguriert JavaMailSender automatisch anhand der Eigenschaften spring.mail.*.

Warum so. SMTP ist ein universelles Protokoll, das von jedem Anbieter unterstützt wird. Der Versandcode weiß nichts über Resend oder SendGrid.

Was das in der Praxis bringt. Ein Umzug von Resend zu SendGrid bedeutet die Änderung von drei Konfigurationszeilen, ohne eine einzige Zeile Java-Code:

# Resend
spring.mail.host=smtp.resend.com
spring.mail.port=587
spring.mail.username=resend
spring.mail.password=${RESEND_API_KEY}

# SendGrid: host=smtp.sendgrid.net, username=apikey, password=${SENDGRID_API_KEY}

spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.connectiontimeout=5000
spring.mail.properties.mail.smtp.timeout=10000
spring.mail.properties.mail.smtp.writetimeout=10000

Beachten Sie zwei Details. Der Benutzername ist eine wörtliche Zeichenfolge: resend bei Resend und apikey bei SendGrid, und der API-Schlüssel selbst wird zum Passwort. Und die Timeouts: Standardmäßig wartet JavaMail unendlich auf die Antwort des Servers. Wenn SMTP "hängt", hängt auch der Thread Ihrer Anwendung.

Der Versand selbst:

MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, "UTF-8");
helper.setFrom("WebCraft <[email protected]>");
helper.setTo(to);
helper.setSubject(subject);
helper.setText(html, true); // true = HTML
mailSender.send(message);

🔌 HTTP API über SDK

Was es ist. Versand über die REST-API des Anbieters mithilfe seiner offiziellen Bibliothek.

Warum so. Die API kann Dinge, die SMTP nicht kann: Sie gibt die E-Mail-ID zurück, unterstützt Tags für Analysen, verzögerte Zustellung, Batch (bei Resend – bis zu 100 E-Mails pro Anfrage) und Idempotenzschlüssel. Mehr dazu im Abschnitt über Wiederholungen.

Was es in der Praxis bedeutet. Mehr Kontrolle und zuverlässigere Wiederholungen, aber der Code ist an einen Anbieter gebunden. Daher ist es sinnvoll, das SDK hinter einer Schnittstelle zu verstecken – darum geht es im nächsten Abschnitt. So sieht der Versand in meinem Projekt aus:

CreateEmailOptions request = CreateEmailOptions.builder()
        .from(fromName + " <" + fromEmail + ">")
        .to(email)
        .subject("📝 Neue Artikel: " + post.getTitle())
        .html(html)
        .build();

CreateEmailResponse response = resend.emails().send(request);
log.info("E-Mail gesendet, ID: {}", response.getId());

🧱 Schnittstelle und @ConditionalOnProperty

Was es ist. Der Geschäftscode hängt von der Schnittstelle EmailSender mit einer einzigen Methode ab, und die spezifische Implementierung (Resend, SMTP, Log) wird über eine Konfigurationseigenschaft ausgewählt.

public interface EmailSender {
    void send(EmailMessage message);
}

public record EmailMessage(String to, String subject, String html, String idempotencyKey) {}

@Service
@ConditionalOnProperty(name = "app.email.provider", havingValue = "resend")
public class ResendEmailSender implements EmailSender { ... }

@Service
@ConditionalOnProperty(name = "app.email.provider", havingValue = "smtp")
public class SmtpEmailSender implements EmailSender { ... }

@Service
@ConditionalOnProperty(name = "app.email.provider", havingValue = "log")
public class LoggingEmailSender implements EmailSender { ... } // schreibt die E-Mail ins Log

Warum so. Der Dienst, der eine Werbeanfrage erstellt oder einen Artikel veröffentlicht, sollte nicht wissen, wer die E-Mail zustellt. Seine Aufgabe ist es, zu sagen „sende diese E-Mail“, nicht „erstelle eine Anfrage an Resend“.

Was es in der Praxis bedeutet:

  • Anbieterwechsel – eine Umgebungsvariable (APP_EMAIL_PROVIDER=smtp auf Railway), ohne Codeänderung und ohne neues Release.
  • Lokal gehen E-Mails ins Log (app.email.provider=log im dev-Profil) – Sie verbrauchen keine Anbieterlimits und senden keine Test-E-Mails an echte Personen.
  • Eine neue Implementierung ist eine einzige Methode send(), nicht das Umschreiben der gesamten E-Mail-Logik.

💡 Aus meiner Erfahrung: In meinem Projekt pflege ich eine separate Konfiguration für jeden Anbieter – den Resend-Client in einer Klasse, den MailerLite-Client in einer anderen. Die gleiche Bedingung @ConditionalOnProperty sollte auch für diese Konfigurationen gelten: dann wird der Client-Bean nur für den aktiven Anbieter erstellt. Ohne dies würde die Anwendung sofort die Schlüssel aller Anbieter benötigen und nicht starten, wenn auch nur einer fehlt.

Ein Rat: Setzen Sie matchIfMissing = true nicht für die Log-Implementierung. Wenn Sie vergessen, die Variable auf der Produktionsumgebung zu setzen, wird die Anwendung stillschweigend E-Mails ins Log „senden“. Ohne sie startet Spring einfach nicht mit einem Fehler bezüglich einer fehlenden EmailSender-Bean – und Sie erfahren sofort von dem Problem, nicht von den Benutzern.

🎨 E-Mail-Vorlagen mit Thymeleaf

Was es ist. Die E-Mail-HTML ist eine normale Thymeleaf-Vorlage in templates/email/, die vor dem Senden in eine Zeichenkette gerendert wird.

Context context = new Context(Locale.of("uk"));
context.setVariable("post", post);
context.setVariable("unsubscribeUrl", unsubscribeUrl);

String html = templateEngine.process("email/new-post", context);
emailSender.send(new EmailMessage(email, subject, html, idempotencyKey));

Warum so. Die Vorlage lebt in Git neben dem Code: mit Änderungsverlauf, Überprüfungen und der Möglichkeit, zurückzusetzen. Sie kann im Browser geöffnet und die Darstellung der E-Mail betrachtet werden.

Was es in der Praxis bedeutet. Vorlagen sind anbieterunabhängig. Wenn Sie sie in Dynamic Templates von SendGrid oder Templates von Resend speichern, müssen Sie bei einem Umzug jede Vorlage übertragen und neu schreiben. Mit Ihrem eigenen Templating-System erhält der Anbieter bereits fertiges HTML.

💡 Aus meiner Erfahrung: Derzeit wird die HTML-E-Mail über String.format direkt in der Anbieterklasse erstellt – 200+ Zeilen CSS und Markup in Java. Das Ändern des Button-Textes erfordert eine Änderung der Java-Klasse und ein neues Deployment. Genau deshalb wandern die Vorlagen zu Thymeleaf.

Und eine praktische Anmerkung zum Layout: E-Mail-Clients sind keine Browser. Gmail schneidet Teile des CSS aus, und Outlook unterstützt kein Flexbox. Für E-Mails sind Inline-Stile (style="...") und Tabellenlayouts zuverlässiger.

⏱️ Asynchroner Versand mit @Async

Was es ist. Eine Methode mit @Async wird in einem separaten Thread ausgeführt, und die Benutzeranfrage wartet nicht, bis die E-Mail an den Anbieter gesendet wird.

@Async("emailExecutor")
public void sendCampaignCreatedNotification(String email, CampaignDto campaign) {
    try {
        emailSender.send(buildMessage(email, campaign));
    } catch (Exception e) {
        log.error("E-Mail konnte nicht gesendet werden für {}", campaign.trackingCode(), e);
    }
}

Warum so. Die Antwort von SMTP oder der API des Anbieters kann eine Sekunde oder länger dauern, und manchmal antwortet sie gar nicht. Der Benutzer, der gerade eine Anfrage erstellt hat, muss nicht darauf warten.

Was es in der Praxis bedeutet. Die Antwort kommt sofort, und wenn der Anbieter ausfällt, wird die Anfrage trotzdem erstellt, nur die E-Mail kommt nicht an (wie man das behebt, wird im Abschnitt über Wiederholungen behandelt).

Drei Fallen, in die man leicht tappen kann:

  • Selbstaufruf funktioniert nicht. Wenn eine Methode mit @Async aus einer anderen Methode desselben Klasse aufgerufen wird, wird sie synchron ausgeführt: der Aufruf geht am Spring-Proxy vorbei. Die asynchrone Methode muss sich in einem separaten Bean befinden – bei mir ist das NotificationService.
  • Eine Ausnahme in einer void-Methode wird von niemandem gesehen, wenn sie nicht protokolliert wird. Daher try/catch innen.
  • Legen Sie Ihren eigenen Thread-Pool mit einer begrenzten Warteschlange und einem verständlichen Namenspräfix (email-) fest, damit E-Mails nicht mit anderen Hintergrundaufgaben konkurrieren und in den Logs sichtbar sind.

🔒 E-Mail nach Transaktions-Commit

Was es ist. Anstatt den Versand direkt aufzurufen, veröffentlicht der Dienst ein Ereignis, und ein Listener, der nur nach erfolgreichem Commit ausgelöst wird, sendet die E-Mail.

Warum so. Hier ist eine reale Methode aus meinem Projekt – die Erstellung einer Werbeanfrage:

@Transactional
public CampaignStatusResponse createCampaign(CampaignCreateRequest request) {
    AdCampaign saved = campaignRepository.save(campaign);
    notificationService.sendCampaignCreatedNotification(request.getContactEmail(), saved);
    return adsMapper.toStatusResponse(saved);
}

Das sieht logisch aus, aber der Versand startet innerhalb der Transaktion. Der asynchrone Thread kann die E-Mail „Anfrage erfolgreich erstellt“ senden, noch bevor der Commit erfolgt. Wenn der Commit später fehlschlägt (z. B. aufgrund einer Einzigartigkeitsbeschränkung, die beim Speichern in der Datenbank geprüft wird), erhält der Kunde eine E-Mail mit dem Code einer Anfrage, die nicht in der Datenbank vorhanden ist.

Wie es richtig geht:

// Im Dienst – nur das Ereignis
@Transactional
public CampaignStatusResponse createCampaign(CampaignCreateRequest request) {
    AdCampaign saved = campaignRepository.save(campaign);
    events.publishEvent(new CampaignCreatedEvent(saved.getId(), request.getContactEmail()));
    return adsMapper.toStatusResponse(saved);
}

// E-Mail – nach dem Commit und in einem separaten Thread
@Async("emailExecutor")
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void onCampaignCreated(CampaignCreatedEvent event) { ... }

Was es in der Praxis bedeutet. Die E-Mail wird nur dann gesendet, wenn die Daten definitiv in der Datenbank sind. Transaktionsrückgängigmachung – keine E-Mail.

Zwei Details. Übergeben Sie in das Ereignis die ID und einfache Werte, keine JPA-Entität: nach dem Commit ist sie bereits vom Session „abgetrennt“, und der Zugriff auf Lazy-Felder führt zu einer Ausnahme. Und wenn das Ereignis außerhalb einer Transaktion veröffentlicht wird, ignoriert der AFTER_COMMIT-Listener es stillschweigend – für solche Fälle gibt es den Parameter fallbackExecution = true.

🔁 Wiederholungen und Fehler

Was das ist. Fehler werden in temporäre, die wiederholt werden sollten, und permanente, deren Wiederholung zwecklos ist, unterteilt.

Warum so. Anbieterfehler sind zweierlei:

  • Temporäre: 429 und 5xx. Das Anfragelimit wurde überschritten oder der Anbieter hat eine Störung. In ein oder zwei Sekunden wird die Anfrage wahrscheinlich erfolgreich sein.
  • Permanente: 400, 401, 403, 422. Falsche Adresse, ungültiger Schlüssel, nicht verifizierte Domain. Eine Wiederholung führt zum selben Fehler – sie verbraucht nur das Limit.

Daher sollte bei der Implementierung eines Anbieters der Fehler in eine von zwei eigenen Ausnahmen umgewandelt werden:

if (status == 429 || status >= 500) {
    throw new TransientEmailException(e);   // kann wiederholt werden
}
throw new PermanentEmailException(e);       // Wiederholung ist zwecklos

Und nur die erste mit einer exponentiell steigenden Pause (Backoff) wiederholen:

// Spring Boot 4 / Spring Framework 7 — integriert, plus @EnableResilientMethods in der Konfiguration
@Retryable(includes = TransientEmailException.class, maxRetries = 3, delay = 1000, multiplier = 2)
public void send(EmailMessage message) { ... }

// Spring Boot 3 — Spring Retry Bibliothek, plus @EnableRetry
@Retryable(retryFor = TransientEmailException.class, maxAttempts = 4,
           backoff = @Backoff(delay = 1000, multiplier = 2))

Was das in der Praxis bringt. Kurze Anbieterstörungen werden automatisch „geschluckt“, und eine fehlerhafte E-Mail wird nicht wiederholt versendet.

Idempotenzschlüssel. Es gibt einen unangenehmen Fall: Der Anbieter hat die E-Mail angenommen, aber die Antwort ist aufgrund eines Timeouts nicht angekommen. Sie wiederholen den Vorgang – und der Kunde erhält zwei identische E-Mails. Der Idempotenzschlüssel löst dieses Problem: Resend speichert den Schlüssel 24 Stunden lang und sendet bei einer erneuten Anfrage mit demselben Schlüssel die E-Mail nicht erneut. Der Schlüssel muss die E-Mail eindeutig beschreiben:

String key = "campaign-created/" + campaignId;     // für API — Header Idempotency-Key
                                                    // für SMTP — Header Resend-Idempotency-Key

Was tun, wenn der Anbieter länger ausfällt. Wiederholungen im Speicher helfen nicht, wenn die Störung eine Stunde dauert oder die Anwendung neu gestartet wird. Dann ist es zuverlässiger, E-Mails in einer Tabelle zu speichern (Status, Anzahl der Versuche, Zeitpunkt des nächsten Versuchs) und sie mit einer geplanten Aufgabe zu versenden. Eine E-Mail, die in derselben Transaktion wie die Anfrage gespeichert wird, geht weder bei einer Anbieterstörung noch bei einem Deployment verloren.

❓ FAQ

Was soll ich für Spring Boot wählen: SMTP oder API-Anbieter?

SMTP – wenn Unabhängigkeit vom Anbieter wichtig ist und eine einfache Sendung benötigt wird. API – wenn Idempotenz, Batch-Versand, Tags und E-Mail-IDs benötigt werden. Verbergen Sie in beiden Fällen die Implementierung hinter einer Schnittstelle.

Warum kann ich keine E-Mail direkt innerhalb einer @Transactional-Methode senden?

Die E-Mail wird auch dann gesendet, wenn die Transaktion später zurückgerollt wird. Der Benutzer erhält eine Bestätigung für eine Aktion, die nicht in der Datenbank vorhanden ist. Verwenden Sie @TransactionalEventListener mit der Phase AFTER_COMMIT.

Warum funktioniert @Async nicht?

Der häufigste Grund ist der Aufruf aus derselben Klasse: Er umgeht den Spring-Proxy und wird synchron ausgeführt. Lagern Sie die asynchrone Methode in einen separaten Bean aus und stellen Sie sicher, dass @EnableAsync aktiviert ist.

Welche Anbieterfehler sollten wiederholt werden?

Nur temporäre: 429 (Anfragelimit) und 5xx (Anbieterseitige Störung). 4xx-Fehler wie falsche Adresse oder Schlüssel sind zwecklos zu wiederholen.

Spring Retry oder @Retryable mit Spring Framework 7?

In Spring Boot 4 (Spring Framework 7) ist @Retryable in das Framework selbst integriert und ersetzt das separate Projekt Spring Retry. In Spring Boot 3 verwenden Sie die Spring Retry-Bibliothek.

✅ Schlussfolgerungen

  • SMTP bietet Unabhängigkeit vom Anbieter, API mehr Möglichkeiten. Verbergen Sie beide Optionen hinter einer Schnittstelle.
  • Schalten Sie den Anbieter über @ConditionalOnProperty und eine Umgebungsvariable um – ohne Codeänderung und ohne neuen Release.
  • Halten Sie E-Mail-Vorlagen auf Ihrer Seite – so wird der Umzug zu einem anderen Anbieter die Vorlagen nicht beeinträchtigen.
  • Senden Sie asynchron und erst nach dem Commit der Transaktion.
  • Wiederholen Sie nur temporäre Fehler mit Backoff und Idempotenzschlüssel, und speichern Sie bei langen Ausfällen E-Mails in der Datenbank.

📚 Quellen