API-Grundlagen

Limits & Fehler

Wiederholungsversuche sicher handhaben, die Nachrichtenidentität bewahren und vorhersehbare Integrationen erstellen.

Anfragelimits

Jeder Tarif ist berechtigt, sobald Integrationen aktiviert sind. Die bestehenden Speicher-, Sende- und Ressourcenlimits des Kontos gelten weiterhin.

Limit	Maximum
Pro Zugangsdaten	120 Anfragen / Minute
Pro Konto	600 Anfragen / Minute
Listenseite	100 Elemente
Anfragetext / lesbare Nachricht	10 MiB
Text und HTML	1,000,000 Zeichen jeweils
Anhänge	10 Dateien, insgesamt 5 MiB decodiert
Empfänger	20 Empfänger insgesamt in An, Cc und Bcc

Prüfe die Rate-Limit-Header und beachte Retry-After bei einer 429-Antwort. Verwende IMAP, um Nachrichten zu lesen, die größer als 10 MiB sind.

Cursor-Paginierung

Ressourcenlisten geben einen undurchsichtigen next_cursor zurück. Übergib genau diesen Wert als Query-Parameter cursor der nächsten Anfrage. Dekodiere keine Cursor und erstelle sie nicht selbst.

Nachrichtenlisten verwenden den numerischen Wert nextCursor und geben uidValidity zurück. Behalte beide Werte bei, wenn du eine Nachrichtenliste fortsetzt. Die Standardseitengröße beträgt 25, maximal sind 100.

Wiederholungsversuche sicher machen

Für Änderungsanfragen ist ein Idempotency-Key erforderlich: 8–128 Buchstaben, Ziffern, Unterstriche, Punkte oder Bindestriche. Verwende für jede bewusst ausgelöste Aktion einen anderen Schlüssel. Wiederhole nach einer Unterbrechung denselben Schlüssel mit einer identischen Anfrage.

Idempotenz-Header

Idempotency-Key: order-confirmation-1042

Die Wiederverwendung eines Schlüssels mit anderen Eingabedaten führt zu einem Konflikt. Antworten auf Erstellungs- und Änderungsanfragen enthalten eine dauerhafte Vorgangs-ID zur Fortschrittsprüfung.

Sende eine unsichere Übermittlung nicht automatisch erneut

Ein uneindeutiges SMTP-Ergebnis wurde möglicherweise bereits angenommen. Prüfe den Versandbeleg, bevor du entscheidest, was zu tun ist. Wenn du mit einem neuen Schlüssel erneut sendest, kann die E-Mail doppelt zugestellt werden.

Nachrichtenidentität beibehalten

Eine Nachrichtenreferenz kombiniert E-Mail-Postfach-ID, Ordner, uidValidity und uid. Bewahre alle vier Angaben auf. Eine veraltete Referenz gibt 409 zurück; rufe den Ordner erneut ab, statt die UID bei geändertem Postfachstatus wiederzuverwenden.

Das Löschen einer Nachricht verschiebt die E-Mail standardmäßig in den Papierkorb. Für das endgültige Löschen ist permanent: true erforderlich. Verwende den Lösch-Endpunkt, um die Nachricht in den Papierkorb zu verschieben. Über den Verschiebe-Endpunkt lassen sich die Löschberechtigungen nicht umgehen.

Fehler einheitlich behandeln

Beispiel für eine Fehlerstruktur

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient permission.",
    "request_id": "example-request-id"
  }
}

Status	Bedeutung
`400`	Ungültige Eingabe oder fehlender Idempotenzschlüssel.
`401`	Fehlende, abgelaufene oder widerrufene Zugangsdaten.
`403`	Unzureichende Berechtigung, falscher Verwendungszweck der Zugangsdaten oder fehlende E-Mail-Postfachfreigabe.
`404`	Ressource nicht gefunden oder für diese Integration nicht verfügbar.
`409`	Ressourcenkonflikt, veraltete UID oder widersprüchliche Idempotenzangabe.
`413`	Anfrage oder Nachricht überschreitet die unterstützte Größe.
`429`	Ratenlimit erreicht. Retry-After beachten.
`503`	Integrationen deaktiviert oder ein vorgelagerter Dienst nicht verfügbar.

Gib error.request_id an, wenn du den Support kontaktierst. Ein ungewisses Sendeergebnis muss als möglicherweise angenommen behandelt werden.

Als NächstesSignierte Webhooks empfangen