API-Keys - letr.dev

Jeder Aufruf von /v1 und des MCP-Servers trägt einen Key als Authorization: Bearer letr_.... Keys erstellen Sie im Dashboard; das Secret erscheint einmal.

Berechtigungen

sending_access, der Standard für neue Keys, versendet mit POST /v1/emails und POST /v1/emails/batch und liest bei den E-Mails, die dieser Key versendet hat, die E-Mail mit GET /v1/emails/{id}, ihren Inhalt mit GET /v1/emails/{id}/content und ihre Anhänge mit GET /v1/emails/{id}/content/attachments/{index} und bricht eine geplante mit POST /v1/emails/{id}/cancel ab. Sonst nichts.
read_only darf jedes GET unter /v1 aufrufen: E-Mails, Verbrauch, Kennzahlen, Domains, Webhooks und Sperrliste. Kein Versand, keine Änderungen.
full_access darf alles unter /v1 aufrufen. Zusätzlich zum Lesen versendet ein solcher Key, fügt Domains hinzu, prüft und entfernt sie, ändert, löscht und testet Webhook-Endpunkte und entfernt Adressen von der Sperrliste.

Eine Anfrage ausserhalb der Berechtigung ergibt 403 insufficient_permission. Eine Domain, ein Webhook-Endpunkt oder ein Sperrlisteneintrag eines anderen Kontos ergibt 404 not_found, dieselbe Antwort wie für einen fehlenden Eintrag. Die API-Referenz nennt die Berechtigung jedes Endpunkts.

Key auf Domains beschränken

Ein Key mit sending_access lässt sich auf bis zu 20 Absenderdomains Ihres Kontos beschränken. Er versendet dann nur von diesen; jede andere Absenderdomain ergibt 403 domain_not_allowed. Ohne Beschränkung darf er jede verifizierte Domain verwenden. Geben Sie Agenten und einzelnen Diensten einen Key, der auf eine Domain beschränkt ist.

Key erneuern

Beim Erneuern ersetzt ein neuer Key mit gleichem Namen, gleicher Berechtigung und gleichen Domains den alten. Sie wählen, wie lange der alte weiter funktioniert: sofort, 1 Stunde, 24 Stunden oder 7 Tage. Stellen Sie den neuen Key in dieser Zeit um, dann scheitert nichts. Das Erneuern storniert sofort die vom alten Key geplanten E-Mails, die nach seiner Frist fällig sind; die vorher fälligen bleiben. Planen Sie die stornierten mit dem neuen Key und einem neuen Idempotency-Key erneut: Der alte würde die stornierte E-Mail wiedergeben. Ein neuer Key mit sending_access hat eine neue ID und liest die E-Mails des alten Keys nicht; ein Key mit read_only oder full_access liest sie alle. Nach der Frist ergibt der alte Key 401. Ein Key, der bereits ersetzt wird, lässt sich nicht nochmals erneuern (422 api_key_expiring); erneuern Sie stattdessen seinen Nachfolger. Ein widerrufener Key funktioniert sofort nicht mehr: Offene SMTP-Sitzungen mit diesem Key enden bei ihrer nächsten Nachricht, und die geplanten E-Mails, die er erstellt hat, werden storniert.

Kein Key verwaltet Keys

Kein API-Key kann API-Keys auflisten, erstellen, erneuern oder widerrufen, egal mit welcher Berechtigung; dafür braucht es eine angemeldete Person im Dashboard. Ein abgeflossener Key kann deshalb keine weiteren Keys erstellen und Sie nicht von den anderen aussperren.