Warteschlange zurückgehaltener E-Mails

Keine E-Mail geht jemals stillschweigend verloren. Wenn Frontmail eine Nachricht gerade nicht senden kann – weil Ihre Organisation keine Credits mehr hat oder weil Ihr E-Mail-Dienst die Zugangsdaten abgelehnt hat –, wird die Nachricht angenommen, sicher in der Warteschlange zurückgehaltener E-Mails gespeichert (im Dashboard Zurückgehaltene E-Mails) und automatisch gesendet, sobald das Problem gelöst ist.

Wann E-Mails zurückgehalten werden

Grund	Status	Auslöser
Keine Credits	held	Kein Guthaben mit verbleibenden Credits (Kontingent, Credit-Pakete und Überziehung aufgebraucht) und die Organisation nutzt den Modus `hold`
Dienstfehler	held_service_error	Der Anbieter hat die Zugangsdaten abgelehnt (Authentifizierungsfehler) und die Vorlage hat keinen funktionierenden Ersatzdienst

Bei fehlenden Credits antwortet die API sofort:

HTTP/1.1 202 Accepted

{ "message_id": "msg_01J9Z3K7Q2", "status": "held", "status_token": "…" }

Die SDKs liefern status: 'held' zurück – das ist ein Erfolg, kein Fehler. Zeigen Sie Ihren Besuchern eine normale Bestätigung; die E-Mail geht raus, sobald wieder Credits vorhanden sind.

Zurückhaltungen wegen eines Dienstfehlers entstehen erst später, beim Versand: Die Nachricht wurde als queued angenommen, der Anbieter hat die Zugangsdaten abgelehnt, der Credit wurde zurückerstattet und die Nachricht wechselte zu held_service_error.

Wie lange E-Mails zurückgehalten werden

Tarif	Aufbewahrungsdauer
Free	3 Tage
Starter, Pro, Business	14 Tage

Die Dauer zählt ab dem Moment, in dem die Nachricht zurückgehalten wurde, und richtet sich nach dem Tarif, den Sie zu diesem Zeitpunkt nutzen. Laufen zurückgehaltene E-Mails innerhalb der nächsten 24 Stunden ab, erhalten Inhaber, Admins und Mitglieder mit der Rolle Abrechnung die E-Mail „Zurückgehaltene E-Mails laufen bald ab“ (höchstens einmal am Tag). Nachrichten, die das Ende der Aufbewahrungsdauer erreichen, werden verworfen (Status discarded), und dieselben Personen erhalten eine E-Mail mit der Liste dieser Nachrichten und einem Link zum Download der vollständigen Liste als CSV. Eine zurückgehaltene E-Mail wird nie verworfen, ohne dass jemand davon erfährt.

Limit der Warteschlange

Eine Organisation kann höchstens 10 % des monatlichen Kontingents ihres Tarifs zurückhalten – mindestens 1.000 und höchstens 10.000 Nachrichten (Free, Starter, Pro: 1.000; Business 50k: 5.000; Business 100k und 200k: 10.000). Ist die Warteschlange voll, werden neue Anfragen ohne Credits mit 402 insufficient_credits und details.reason: "hold_queue_full" abgelehnt, statt zurückgehalten zu werden. So kann niemand, der Ihren öffentlichen Schlüssel kopiert hat, die Warteschlange mit Müll füllen, der – freigegeben in der Reihenfolge ältester zuerst – jeden neuen Credit vor Ihren echten Nachrichten verbrauchen würde. Um Platz zu schaffen, geben Sie zurückgehaltene E-Mails frei, verwerfen Sie sie oder kaufen Sie Credits.

Automatische Freigabe

Frontmail gibt die Warteschlange automatisch frei, sobald Credits hinzukommen:

Sie kaufen ein Credit-Paket,
eine automatische Aufladung ist erfolgreich,
Sie führen ein Upgrade Ihres Tarifs durch,
ein neuer Abrechnungszeitraum beginnt (Verlängerung des Abonnements; Free: neuer Kalendermonat),
der Frontmail-Support schreibt Ihnen Bonus-Credits gut.

…und bei Nachrichten mit held_service_error, sobald der Dienst wieder funktioniert (Zugangsdaten aktualisiert, OAuth neu verbunden oder eine erfolgreiche Statusprüfung).

Die Freigabe verarbeitet zurückgehaltene E-Mails in der Reihenfolge ältester zuerst. Für jede Nachricht reserviert sie einen Credit, setzt sie zurück auf queued und übergibt sie dem Versand. Sie hält bei der ersten Nachricht an, für die kein Credit mehr da ist – der Rest bleibt in der gleichen Reihenfolge zurückgehalten. Die Freigabe kann gefahrlos parallel laufen; eine Nachricht wird nie doppelt gesendet.

Nachrichten, die mit dem öffentlichen Schlüssel gesendet wurden, werden automatisch nur aus anderen Credits als der Überziehung freigegeben – es sei denn, Sie erlauben Traffic mit öffentlichem Schlüssel deren Nutzung unter Abrechnung → Credits kaufen → Ausgaben durch Traffic mit öffentlichem Schlüssel. Ist nur noch die Überziehung übrig, bleiben solche Nachrichten zurückgehalten, während andere freigegeben werden. Eine manuelle Freigabe im Dashboard darf für sie die Überziehung verwenden.

Zurückgehaltene E-Mails werden mit der Vorlagenversion gerendert, die bei ihrer Annahme aktuell war.

Manuell freigeben und verwerfen

Zurückgehaltene E-Mails im Dashboard listet alle zurückgehaltenen Nachrichten auf, die ältesten zuerst, mit den Spalten Zurückgehalten seit, Vorlage (mit Betreff), Empfänger, Grund und Läuft ab. Zeilen, die innerhalb von 24 Stunden ablaufen, sind hervorgehoben. Nach dem Grund filtern Sie mit Alle / Keine Credits / Dienstfehler. Inhaber, Admins und Entwickler können:

N freigeben – die ausgewählten Nachrichten freigeben. Praktisch, nachdem Sie einen Dienst repariert haben, oder um bei wenigen Credits die wichtigsten Nachrichten zuerst zu senden. Die Nachrichten werden – die ältesten zuerst – freigegeben, solange Credits vorhanden sind; der Rest bleibt zurückgehalten, und das Dashboard weist Sie darauf hin.
Alle freigeben – alle zurückgehaltenen Nachrichten freigeben, die ältesten zuerst, soweit die Credits reichen.
N verwerfen – die ausgewählten Nachrichten nach einer Bestätigung verwerfen. Sie werden nie gesendet und verbrauchen keine Credits. Das lässt sich nicht rückgängig machen.

Inhaber und Mitglieder mit der Rolle Abrechnung sehen auf der Seite außerdem die Schaltfläche Credits kaufen. Nutzt Ihre Organisation den Modus reject, weist die Seite darauf hin, dass neue Anfragen abgelehnt statt zurückgehalten werden.

Die obere Leiste des Dashboards zeigt immer an, wie viele Credits noch übrig sind (Noch N Anfragen). Ein Klick darauf zeigt die Aufschlüsselung nach Quelle (Abonnement, Credit-Pakete, Bonus, Überziehung) und den nächsten Ablauftermin. Sind E-Mails zurückgehalten, erscheint daneben ein rotes Badge mit ihrer Anzahl, das auf Zurückgehaltene E-Mails verlinkt.

Modus `hold` oder `reject`

Jede Organisation legt fest, was ohne Credits passiert – unter Sicherheit → Wenn Ihre Credits aufgebraucht sind (Inhaber und Admins):

Modus	Antwort	Geeignet, wenn
E-Mails zurückhalten (`hold`, Standard, empfohlen)	`202` mit `status: "held"`, die Nachricht wird gespeichert und später gesendet	Eine späte Zustellung besser ist als keine – Kontaktformulare, Bestellungen, Buchungen
Anfragen ablehnen (`reject`)	`402` `insufficient_credits`, nichts wird gespeichert	Eine späte Zustellung schlimmer ist als keine (Einmalcodes, zeitkritische Warnungen) und Ihr Code den Fehler behandelt

Im Modus reject werfen die SDKs einen InsufficientCreditsError. Zurückhaltungen wegen eines Dienstfehlers (held_service_error) gibt es in beiden Modi, weil die Anfrage bereits angenommen wurde.

Benachrichtigungen

E-Mail	Wann	Empfänger
E-Mails warten – Ihre Credits sind aufgebraucht	Wenn in einem Kalendermonat zum ersten Mal eine Nachricht zurückgehalten wird	Inhaber, Admins, Abrechnung
Zurückgehaltene E-Mails laufen bald ab	Höchstens einmal am Tag, solange zurückgehaltene E-Mails innerhalb von 24 Stunden ablaufen	Inhaber, Admins, Abrechnung
Zurückgehaltene E-Mails wurden verworfen	Nach dem Ablauf, mit der Liste der verworfenen Nachrichten und einem CSV-Link	Inhaber, Admins, Abrechnung
Dienst funktioniert nicht / funktioniert wieder	Wenn die Authentifizierung eines Dienstes fehlschlägt / wieder klappt	Inhaber, Admins

Alle E-Mails finden Sie unter Benachrichtigungen.

Status im Code prüfen

const res = await send('svc_01J9…', 'tpl_order', params);
if (res.status === 'held') {
  // Angenommen und sicher – wird automatisch gesendet.
}

// Später (Clients mit öffentlichem Schlüssel brauchen das Status-Token aus dem Sendeergebnis):
const status = await getStatus(res.messageId, { token: res.statusToken });
console.log(status.status); // "held" → "queued" → "sent" …