API-Schlüssel
API-Schlüssel mit vollem oder reinem Sendezugriff erstellen, auf eine Domain oder ein Postfach beschränken und verwalten.
Ein API-Schlüssel ist das Geheimnis, das Ihr Code bei jeder Anfrage mitsendet. Erstellen Sie einen unter API-Schlüssel im Dashboard oder mit der API selbst. Ein Schlüssel wird nur einmal angezeigt, beim Erstellen, speichern Sie ihn also in Ihrem Secret-Manager.
curl https://api.billionsend.com/emails \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"from": "hello@example.com",
"to": "success@simulator.amazonses.com",
"subject": "Hi",
"text": "Hello."
}'
Schlüssel beginnen mit bs_. BillionSend speichert nur einen Hash des Schlüssels, ein verlorener Schlüssel lässt sich daher nicht erneut anzeigen: Widerrufen Sie ihn und erstellen Sie einen neuen.
Einen Schlüssel erstellen
Öffnen Sie im Dashboard API-Schlüssel und wählen Sie API-Schlüssel erstellen. Inhaber, Admins und Entwickler können das tun; siehe Teamrollen. Wählen Sie:
- Name: 1 bis 80 Zeichen, damit Sie Schlüssel unterscheiden können. Sie können ihn später umbenennen.
- Berechtigung: Vollzugriff oder Nur Versand.
- Domain: Beliebige Domain oder eine verifizierte Domain Ihres Teams.
- Auf ein Postfach beschränken (erscheint, sobald Sie Postfächer haben): das eine Postfach, auf das der Schlüssel beschränkt ist.
Mit der API:
curl -X POST "https://api.billionsend.com/api-keys" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production",
"permission": "sending_access",
"domain_id": "af8ad875-319f-4df5-a359-4f2430f3e766"
}'
Die Antwort ist { "id": "…", "token": "bs_…" }: Das Token erscheint nur hier. GET /api-keys listet aktive Schlüssel auf (nie ihre Tokens), und DELETE /api-keys/{id} widerruft einen sofort; Anfragen mit ihm schlagen unmittelbar fehl.
Berechtigung
| Berechtigung | Darf |
|---|---|
| Vollzugriff | Jeden Endpunkt nutzen: Versand, Kontakte, Segmente, Themen, Newsletter-Versände, Domains, Webhooks, Vorlagen, empfangene E-Mails und API-Schlüssel. Ein auf eine Domain beschränkter Schlüssel erreicht davon nur einen Teil. |
| Nur Versand | E-Mails senden (POST /emails, POST /emails/batch) und nichts sonst. Alles außerhalb des Versands und jedes Lesen gespeicherter E-Mails antwortet mit 403 restricted_api_key. |
Verwenden Sie in der App, die Transaktionsmails sendet, einen Schlüssel mit „Nur Senden“. Ein geleakter Schlüssel mit „Nur Senden“ kann Ihre Kontakte nicht lesen, Ihre Domains nicht ändern und keine weiteren Schlüssel erstellen.
Einen Schlüssel auf eine Domain beschränken
Ein auf eine Domain beschränkter Schlüssel arbeitet innerhalb dieser einen Domain und erreicht nichts, was zum gesamten Team gehört. Eine Domain muss verifiziert sein, bevor Sie einen Schlüssel auf sie beschränken können; die Subdomain des gemeinsamen Postfachs ist nicht nutzbar.
| Was | Was der Schlüssel darf |
|---|---|
| Versand, E-Mails, empfangene E-Mails, Postfächer, Abmeldungen, Newsletter-Versände | Nur die dieser Domain. Eine Anfrage für eine andere Domain antwortet mit 403 restricted_api_key. |
GET /emails/metrics |
Liest nur die Zahlen dieser Domain; wird in domain_id eine andere Domain genannt, antwortet es mit 403 restricted_api_key. |
GET /domains und /domains/{id} (lesen, ändern, löschen, verifizieren) |
Listet und berührt nur die eigene Domain. Jede andere Domain, auch die gemeinsame Subdomain, antwortet mit 404. |
/api-keys |
POST erstellt Schlüssel, die auf dieselbe Domain beschränkt sind. GET listet und DELETE widerruft nur Schlüssel, die auf diese Domain beschränkt sind; jeder andere Schlüssel antwortet mit 404. |
| Kontakte, Segmente, Themen | Erlaubt. Kontakte sind das gemeinsame Adressbuch des Teams, aber der Schlüssel kann eine teamweite Abmeldung nicht aufheben. Ein Segment oder Thema, das er anlegt, wird an seine eigene Domain gebunden, und er kann keines lösen. |
Webhooks (jede Methode, auch das Signing-Secret), Sperrlisten, Vorlagen, Kontakteigenschaften, GET /usage, GET /deliverability, Verifizierungen und POST /domains |
403 restricted_api_key: Diese gehören zum gesamten Team. |
Nutzen Sie einen solchen Schlüssel für einen Dienst, der zu einer einzelnen Marke gehört: Wenn er leakt, erreicht er die Domain dieser Marke und sonst nichts, weder Ihre Webhooks noch Ihre anderen Schlüssel oder Domains.
Einen Schlüssel auf ein Postfach beschränken
Ein Postfach-Schlüssel gibt einem KI-Agenten Zugriff auf ein Postfach und sonst nichts. Er braucht vollen Zugriff, lässt sich nicht zugleich auf eine Domain beschränken und kann nur für dieses Postfach lesen, antworten, weiterleiten und Entwürfe senden sowie nur von dessen Adresse senden. Er funktioniert nicht mehr, wenn das Postfach abläuft oder gelöscht wird.
Limits
| Limit | Wert |
|---|---|
| Aktive Schlüssel pro Team | 25, SMTP-Zugangsdaten eingeschlossen. Widerrufen Sie einen, um einen weiteren zu erstellen (sonst 422). |
| Aktive Schlüssel pro Postfach | 5, außerhalb der 25 des Teams. |
| Anfragen | 600 pro Minute und Schlüssel und 3.000 pro Team; siehe API-Grundlagen. |
Wer welchen Schlüssel erstellen darf
- Im Dashboard erstellen Inhaber, Admins und Entwickler Schlüssel.
- Ein Schlüssel, den Sie mit der API erstellen, ist nie umfassender als der Schlüssel, der ihn erstellt hat: Ein Schlüssel mit „Nur Senden“ kann nur Schlüssel mit „Nur Senden“ erstellen, ein auf eine Domain beschränkter Schlüssel kann nur Schlüssel für diese Domain erstellen (und sieht und widerruft nur diese), und ein Postfach-Schlüssel kann keine Schlüssel erstellen.
- Ein Schlüssel handelt mit der Teamrolle, die sein Ersteller heute hat, bei jeder Anfrage neu geprüft. Der Ersteller ist die Person, die ihn im Dashboard erstellt hat (oder die App verbunden hat, die ihn erstellt hat); ein über die API erstellter Schlüssel übernimmt den Ersteller des Schlüssels, der ihn erstellt hat. Die Rolle schränkt die alltägliche Arbeit nicht ein: Ein Schlüssel mit vollem Zugriff sendet und verwaltet Kontakte, Newsletter-Versände, Domains, Webhooks und Schlüssel, welche Rolle sein Ersteller auch hat (ein auf eine Domain beschränkter Schlüssel ist die Ausnahme, siehe oben). Die Aktionen mit hohem Risiko (einen Empfänger löschen, eine Sperre entfernen, eine Abmeldung zurücknehmen) erfordern einen Schlüssel, dessen Ersteller gerade Inhaber oder Admin ist; andere Schlüssel antworten mit
403 forbidden. Wird der Ersteller herabgestuft, folgen seine Schlüssel ab der nächsten Anfrage der neuen Rolle. Wird er aus dem Team entfernt oder verlässt es, funktionieren alle API-Schlüssel, die er erstellt hat, die Schlüssel, die diese Schlüssel erstellt haben, und seine Agent-Schlüssel sofort nicht mehr (401 invalid_api_key) und erscheinen als widerrufen; eine erneute Einladung bringt sie nicht zurück. Siehe Teamrollen.
Das Erstellen, Umbenennen und Widerrufen eines Schlüssels wird im Audit-Log festgehalten.
Weitere Schlüssel
- SMTP-Zugangsdaten sind Schlüssel mit „Nur Senden“, die auf der Seite SMTP für das SMTP-Relay erstellt werden.
- Agent-Schlüssel (
bs_agent_…) sind nur für den MCP-Server gedacht. Sie werden unter MCP erstellt, sind auf „nur lesen“, „lesen und antworten“ oder „lesen und senden“ beschränkt, und ein Team besitzt bis zu 20. Ihre regulären API-Schlüssel funktionieren auf dem MCP-Server nicht.