Fehler und Limits der E-Mail-API: Statuscodes, Retries und Monitoring

Eine einzelne E-Mail in einer Demo zu versenden ist einfach. Hunderttausend pro Monat in Produktion zu versenden heißt, die Momente einzuplanen, in denen etwas schiefgeht: ein widerrufener Schlüssel, eine abgelaufene Kreditkarte, ein Monat, der früher endet als erwartet, ein Mailserver mit einem schlechten Tag.

Dieser Leitfaden erklärt jede Antwort, die der Inbixio-Sende-Endpunkt zurückgibt, was Ihr Code jeweils tun sollte und wie Sie die Zustellung überwachen, sobald Sie live sind.

Zwei Phasen: angenommen, dann zugestellt

Ein Aufruf von POST /api/send-email/ läuft in zwei Phasen ab:

1. Die API-Anfrage. Inbixio prüft Ihren Schlüssel, seine Berechtigungen, Ihr Abonnement, Ihre monatliche Nutzung und den Request-Body. Ist alles in Ordnung, gibt die API 200 zurück und reiht die Nachricht ein.
2. Die Zustellung. Einen Moment später verbindet sich Inbixio mit Ihrem SMTP-Server und übergibt die Nachricht. Jede Nachricht wird als gesendet oder fehlgeschlagen erfasst, und diese Ergebnisse fließen in die Kennzahlen Ihres Dashboards ein.

Ein 200 bedeutet also „zur Zustellung angenommen“, nicht „im Posteingang“. Probleme in Phase 1 kommen als HTTP-Fehler zurück, die Ihr Code behandeln kann. Probleme in Phase 2, etwa ein falsches SMTP-Passwort, zeigen sich in der Rate fehlgeschlagener Zustellungen im Dashboard. Inbixio unternimmt pro Nachricht einen Zustellversuch; eine fehlgeschlagene Zustellung wird nicht wiederholt.

Jede Antwort – und was zu tun ist

Fehlermeldungen stehen bei den meisten Antworten unter error und bei Authentifizierungsfehlern unter detail. Lesen Sie daher beide:

const body = await res.json().catch(() => ({}));
const reason = body.error ?? body.detail ?? res.statusText;

Nur wiederholen, was später gelingen kann

Einen 401 hundertmal zu wiederholen, macht den Schlüssel nicht gültig – es füllt nur Ihre Logs. Teilen Sie Fehler in zwei Gruppen auf:

• Wiederholen: Netzwerkfehler, Timeouts, 5xx-Antworten und der Rate-Limit-429 (der mit einer detail-Meldung). Warten Sie so lange, wie der Retry-After-Header angibt, andernfalls nutzen Sie exponentiellen Backoff mit Jitter, und geben Sie nach einigen Versuchen auf.
• Nicht wiederholen: 400, 401, 402, 403 und der Monatslimit-429 (der mit limit und sent). Hier braucht es einen Menschen oder eine andere Anfrage. Protokollieren Sie diese Fehler deutlich sichtbar und lösen Sie bei 401, 402 und dem Monatslimit-429 einen Alarm aus, denn sie stoppen Ihren gesamten E-Mail-Versand.

// 5xx and the short-term rate limit can succeed later; the monthly limit (body has `limit`) can't.
const retryable = (status, body) => status >= 500 || (status === 429 && body.limit === undefined);

export async function sendWithRetry(payload, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    let res;
    try {
      res = await fetch('https://backend.inbixio.com/api/send-email/', {
        method: 'POST',
        headers: { 'X-API-Key': process.env.INBIXIO_API_KEY, 'Content-Type': 'application/json' },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(15_000),
      });
    } catch (err) {
      if (i === attempts - 1) throw err; // network error or timeout: retry
    }
    if (res?.ok) return res.json();
    if (res) {
      const body = await res.json().catch(() => ({}));
      if (!retryable(res.status, body)) {
        throw new Error(`Inbixio ${res.status}: ${body.error ?? body.detail ?? res.statusText}`);
      }
    }
    const retryAfter = Number(res?.headers.get('Retry-After')) * 1000;
    const delay = retryAfter || Math.min(30_000, 1000 * 2 ** i) * (0.5 + Math.random()); // 0.5s–30s with jitter
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error('Inbixio: gave up after retries');
}

Zu Duplikaten: Wenn bei einer Anfrage ein Timeout auftritt, kann sie trotzdem angenommen worden sein. Ein erneuter Versuch könnte dann dieselbe E-Mail zweimal senden. Bei Quittungen und Benachrichtigungen ist das meist vertretbar; überall dort, wo ein Duplikat Nutzer verwirren würde, speichern Sie in Ihrer eigenen Datenbank, was Sie gesendet haben, und prüfen das vor dem erneuten Versuch.

Monatslimits

Jeder Tarif enthält eine bestimmte Anzahl E-Mails pro Monat: 25.000 bei Starter und 150.000 bei Growth. Inbixio zählt die erfolgreich gesendeten E-Mails im laufenden Kalendermonat. Erreichen Sie das Limit, liefern Sendevorgänge 429 mit Ihrem limit und dem aktuellen sent-Wert zurück – bis der nächste Monat beginnt oder Sie upgraden.

Warten Sie nicht auf den 429:

• Die Seite API Keys (API-Schlüssel) zeigt eine Karte Usage Limit (Nutzungslimit) mit den in diesem Monat gesendeten E-Mails im Verhältnis zu Ihrem Tariflimit.
• Erinnern Sie sich selbst daran, bei etwa 80 % Ihres Limits nachzusehen, und planen Sie ein Upgrade vor einem großen Produktstart oder Import.
• Eine Schritt-für-Schritt-Schätzung des Volumens finden Sie unter E-Mail-API-Tarif wählen.

Zustellfehler (Phase 2)

Hat die API eine Nachricht angenommen, Ihr SMTP-Server sie aber abgelehnt, zählt das als fehlgeschlagene Zustellung. Das Dashboard zeigt die Rate Failed Deliveries (fehlgeschlagene Zustellungen) der letzten 7 Tage statt einer Liste einzelner Nachrichten. Behalten Sie also die Rate im Blick und prüfen Sie Ihre Servereinstellungen, wenn sie steigt. Die üblichen Ursachen:

• Authentifizierung fehlgeschlagen: Das Postfach-Passwort wurde geändert, oder der Anbieter verlangt inzwischen ein App-Passwort.
• Verbindungsprobleme: Host oder Port in Ihren Servereinstellungen sind falsch.
• Anbieterlimits: Ihr Mail-Anbieter hat den täglichen Versand des Postfachs begrenzt.
• Abgelehnter Empfänger: Ihr Server hat die Adresse beim Senden abgewiesen. Bounces, die später als E-Mails eintreffen, gehen an das sendende Postfach, nicht an Inbixio – prüfen Sie also auch diesen Posteingang.

Die Lösung findet sich fast immer unter Email Servers (E-Mail-Server) oder bei Ihrem Mail-Anbieter. SMTP-Einstellungen erklärt behandelt die häufigsten Fälle.

Was Sie in Produktion überwachen sollten

Ihr Inbixio-Dashboard liefert das Wesentliche:

• Email Sent (gesendete E-Mails) und die Rate Failed Deliveries der letzten 7 Tage, jeweils mit der Veränderung gegenüber den 7 Tagen davor.
• Avg Latency (durchschnittliche Latenz): wie lange Ihr SMTP-Server braucht, um E-Mails anzunehmen. Ein plötzlicher Anstieg geht Fehlern oft voraus.
• Diagramme zu API- und E-Mail-Volumen über das Jahr, um Trends und saisonale Spitzen zu erkennen.
• Logs (Protokolle) jedes API-Aufrufs: Event-ID, Endpunkt, Methode, Statuscode, Antwortzeit und Zeitstempel.

Erfassen Sie auf Ihrer Seite die Anzahl der Nicht-200-Antworten nach Statuscode und lösen Sie einen Alarm aus, sobald 401, 402 oder der Monatslimit-429 auftreten. Sie bedeuten, dass der gesamte E-Mail-Versand gestoppt ist – und Ihre Nutzer bemerken das, bevor es Ihre Logs tun.

Checkliste

• 200 als „eingereiht“ behandeln; Zustellergebnisse im Dashboard prüfen
• Bei Fehlerantworten sowohl error als auch detail auslesen
• Nur Netzwerkfehler, Timeouts, 5xx, 503 und den Rate-Limit-429 wiederholen und dabei Retry-After beachten
• Bei 401, 402 und dem Monatslimit-429 alarmieren
• Die Usage-Limit-Karte vor Produktstarts und Importen im Blick behalten
• Die Rate der Failed Deliveries beobachten und SMTP-Einstellungen umgehend korrigieren