Mailtrap E-Mail-Integration
Muster zum Hinzufügen des transaktionalen E-Mail-Versands zu einer Anwendung mit der Mailtrap E-Mail-API und Sandbox, einschließlich Authentifizierung, Umgebungstrennung und häufiger Zustellungsfallen.
Wann aktivieren
- Implementierung einer „E-Mail senden“-Funktion (Anmeldebestätigung, Passwort-Zurücksetzen, Benachrichtigungen, Quittungen)
- Debugging, warum E-Mails in dev/staging nicht ankommen
- Einrichtung der ersten E-Mail-Versand-Integration eines Projekts
- Überprüfung von Code, der eine E-Mail-API direkt ohne Sandbox-Trennung aufruft
Kernkonzepte
Sandbox vs. Produktionstrennung. Mailtrap bietet eine Sandbox-API, die E-Mails abfängt, ohne sie zuzustellen. Diese wird für dev/staging verwendet, sodass Test-E-Mails niemals echte Postfächer erreichen. Der Produktionsversand verwendet einen separaten, mit einer verifizierten Domain verbundenen Endpunkt. Eine Entwicklungsumgebung sollte niemals auf den Produktions-Endpunkt zeigen.
Authentifizierung. Anfragen verwenden ein Bearer-Token im Authorization-Header. Token sind pro Projekt begrenzt; Sandbox und Produktion verwenden in der Regel unterschiedliche Token.
Domain-Verifikation. Für den Produktionsversand muss eine sendende Domain über DNS-Einträge (SPF, DKIM, DMARC) verifiziert werden, bevor Mailtrap an echte Empfänger zustellt. Das Überspringen führt zu stillen Zustellungsfehlern oder dazu, dass E-Mails im Spam-Ordner landen.
Codebeispiele
// Senden über die Mailtrap E-Mail-API (Produktion)
async function sendEmail(to: string, subject: string, html: string) {
const response = await fetch("https://send.api.mailtrap.io/api/send", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.MAILTRAP_API_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: { email: "[email protected]", name: "Your App" },
to: [{ email: to }],
subject,
html,
}),
});
if (!response.ok) {
throw new Error(`Email send failed: ${response.status}`);
}
return response.json();
}
// Gleicher Aufruf, in Nicht-Produktionsumgebungen zur Sandbox umgeleitet
const MAILTRAP_ENDPOINT = process.env.NODE_ENV === "production"
? "https://send.api.mailtrap.io/api/send"
: `https://sandbox.api.mailtrap.io/api/send/${process.env.MAILTRAP_INBOX_ID}`;
Anti-Patterns
| Anti-Pattern | Warum es ein Problem ist | Stattdessen |
|---|---|---|
| Verwendung des Produktions-Endpunkts in dev/test | Echte Test-E-Mails erreichen echte Postfächer, Spam-Beschwerden und Datenlecks sind möglich | Nicht-Produktionsumgebungen zum Sandbox-Endpunkt routen |
| Hartcodierte API-Token im Quellcode | Credential-Leak-Risiko bei Versionskontrolle | Token aus Umgebungsvariablen / Secrets-Manager laden |
| Senden vor Abschluss der Domain-Verifikation | E-Mails schlagen still oder landen im Spam | SPF-/DKIM-/DMARC-Einträge vor dem Produktionsversand verifizieren |
| Keine Wiederholungs-/Fehlerbehandlung bei Sendefehlern | Stille Benachrichtigungsausfälle (z. B. Benutzer erhält kein Passwort-Zurücksetzen) | Antwortstatus prüfen, Fehler protokollieren, umsetzbare Fehler anzeigen |
Best Practices
- Sandbox- und Produktionstoken in getrennten Umgebungsvariablen aufbewahren, nie ein Token umgebungsübergreifend teilen
- DNS-Einträge der sendenden Domain vor jedem Produktionsstart mit E-Mail-Funktion verifizieren
- Zustellungsfehler mit ausreichend Kontext protokollieren (Empfänger, Vorlage, Zeitstempel, Antwortcode)
- E-Mail-Versand als fehleranfälligen Netzwerkaufruf behandeln: in try/catch kapseln, nie den Erfolg annehmen
Verwandte Fähigkeiten
api-and-interface-design, security-and-hardening, ci-cd-and-automation