Transaktionale E-Mail-Workflows um Anwendungs-Events herum entwerfen

Transactional E-Mail-Workflows sind nicht nur "Nachricht versenden bei Event" — sie sind operative Systeme, die Idempotency, Retries, Failure-Handling und Beobachtbarkeit erfordern.

Die zwei häufigsten Anti-Pattern

Anti-Pattern 1: Synchroner Versand im Request-Handler. Die Anwendung wartet, bis der API-Call abgeschlossen ist, bevor sie die HTTP-Response sendet. Bei Anbieter-Latenz hängt die User-Experience.

Anti-Pattern 2: "Fire and forget" ohne Retry. Bei Fehler wird die Mail nicht erneut versucht. Konsequenz: gelegentlich verlorene Mails ohne Indikator.

Pattern: Event-getriebener Versand mit Queue

1. Geschäfts-Event tritt ein (z.B. order_placed)
       ↓
2. Anwendung publiziert Event in Queue (RabbitMQ, SQS, Kafka)
       ↓ HTTP-Response geht zurück an Nutzer
3. Mail-Worker konsumiert Event aus Queue
       ↓
4. Worker baut Mail-Payload, ruft E-Mail-Anbieter API auf
       ↓
5. Bei Erfolg: Event ack. Bei Fehler: Retry mit exponential backoff
       ↓
6. Webhook-Events vom Anbieter (delivered, opened, etc.)
       ↓
7. Webhook-Handler aktualisiert Mail-Status in DB

Idempotency-Strategien

Strategie A: Idempotency-Key beim Anbieter

def send_order_confirmation(order):
    idempotency_key = f"order-confirmation-{order.id}-v1"
    
    response = api.post(
        '/v3/emails',
        json={...},
        headers={'X-Idempotency-Key': idempotency_key}
    )

Strategie B: Idempotency in eigener DB

def send_order_confirmation(order):
    with db.transaction():
        existing = MailLog.find(
            event_type='order_confirmation',
            order_id=order.id
        )
        if existing:
            return existing.message_id
        
        response = api.post('/v3/emails', json={...})
        MailLog.create(
            event_type='order_confirmation',
            order_id=order.id,
            message_id=response['message_id']
        )

Retry-Logik mit exponential Backoff

def send_with_retry(payload, max_attempts=5):
    delays = [1, 5, 30, 300, 1800]  # 1s, 5s, 30s, 5m, 30m
    
    for attempt in range(max_attempts):
        try:
            response = api.post('/v3/emails', json=payload, timeout=15)
            response.raise_for_status()
            return response
        except (HTTPError, Timeout) as e:
            if attempt == max_attempts - 1:
                dead_letter_queue.publish(payload, error=str(e))
                raise MailDeliveryFailure(payload, e)
            
            delay = delays[attempt] + random.uniform(0, delays[attempt] * 0.1)
            time.sleep(delay)

Bei 4xx-Fehlern (Client-Fehler) kein Retry — direkt in DLQ.

Webhook-Verarbeitung

@app.route('/webhooks/email-events', methods=['POST'])
def handle_email_event():
    if not verify_signature(request.headers, request.body):
        abort(401)
    
    events = json.loads(request.body)
    for event in events:
        event_key = f"{event['message_id']}-{event['event']}-{event['timestamp']}"
        if WebhookEventLog.exists(event_key):
            continue
        
        WebhookEventLog.create(event_key=event_key, payload=event)
        
        mail = MailLog.find(message_id=event['message_id'])
        if mail:
            mail.update_status(event['event'], event['timestamp'])
        
        if event['event'] == 'complained':
            suppression.add(mail.recipient_email)
    
    return '', 200

Wichtige Aspekte: Signatur-Verifikation (HMAC-SHA256), idempotente Verarbeitung, strukturierte Status-Updates.

Beobachtbarkeit und Alerting

• Queue-Tiefe: Worker oder Anbieter sind Bottleneck
• Worker-Throughput: Mails/Sekunde
• Anbieter-Latenz: p50, p95, p99
• Fehler-Rate: 4xx vs 5xx
• DLQ-Tiefe: manuelle Untersuchung notwendig
• Webhook-Eingang: proportional zu Versand-Volumen

Häufige Probleme

Problem 1: Mail wird gesendet, aber Empfänger erhält sie nicht. Webhook zeigt "delivered". Möglich: Spam-Filter, falsches DKIM/SPF, IP-Reputation.

Problem 2: Webhook-Verarbeitung langsam. Lösung: asynchron — Webhook-Handler nimmt Event entgegen, gibt sofort 200 zurück.

Problem 3: Idempotency-Logik versagt bei Schema-Änderung. Lösung: Schema-Version im Idempotency-Key.

Problem 4: Workers verarbeiten Events out-of-order. Lösung: Partitionierung (Events für gleichen User immer auf gleichen Worker via Hash).

DACH-spezifische Aspekte

In DACH-Compliance-Audits werden Mail-Logs oft geprüft — typisch verlangt: 6 Monate Aufbewahrung, klare Zuordnung Mail-zu-Geschäftsvorgang, dokumentierte Bounce/Suppression-Verarbeitung.

Bei strikten Compliance-Anforderungen (Banking, Healthcare): zusätzlich Verschlüsselung der Logs at-rest, Access-Audit-Logs, klare Lösch-Konzepte für DSGVO-Anfragen.