API-Grundlagen
Basis-URL, Berechtigungen von API-Schlüsseln, Fehlerliste, Ratenlimits, Idempotenz-Schlüssel und Paginierung der BillionSend-API.
Die Endpunktseiten in der API-Referenz werden aus den Routendefinitionen der API erzeugt. Die OpenAPI-3.1-Spezifikation ist dieselbe Quelle als eine JSON-Datei.
Die API ist kompatibel mit der Resend-API: gleiche Pfade, gleiche Anfrageformen und gleiches Fehlerformat. Rufen Sie sie über die BillionSend-SDKs oder per einfachem HTTP auf.
Basis-URL
https://api.billionsend.com
Authentifizierung
Senden Sie bei jeder Anfrage einen API-Schlüssel aus API-Schlüssel im Dashboard:
Authorization: Bearer bs_...
Ein fehlender oder fehlerhafter Schlüssel antwortet mit 401 missing_api_key, ein falscher mit 401 invalid_api_key.
Ein Schlüssel hat eine Berechtigungsstufe:
- Vollzugriff kann jeden Endpunkt nutzen.
- Nur Versand kann ausschließlich senden. Alles außerhalb von
/emailsantwortet mit403 restricted_api_key, ebensoGET /emails,GET /emails/{id},GET /emails/metrics,DELETE /emails/{id}und jeder Endpunkt unter/emails/receiving, weil sie gespeicherte Inhalte zurückgeben.
Ein Schlüssel lässt sich außerdem auf eine Domain oder auf ein Postfach beschränken. Ein auf eine Domain beschränkter Schlüssel arbeitet innerhalb dieser Domain: Er sendet nur von ihr, liest nur ihre E-Mails, sieht und ändert unter /domains nur sie und antwortet bei allem, was zum gesamten Team gehört (Webhooks, Sperrlisten, Vorlagen, Kontakteigenschaften, /usage, /deliverability, Verifizierungen, POST /domains), mit 403 restricted_api_key; siehe API-Schlüssel. Ein Schlüssel, den Sie mit der API erstellen, ist nie umfassender als der Schlüssel, der ihn erstellt hat.
Ein Team kann 25 aktive Schlüssel haben. Welche Aktionen einen Schlüssel von einem Inhaber oder Admin erfordern, steht unter Teamrollen.
Fehler
Jeder Fehler hat diese Form:
{ "statusCode": 422, "name": "validation_error", "message": "..." }
| Status und Name | Bedeutung |
|---|---|
400 invalid_parameter |
Der Body ist kein gültiges JSON. |
401 missing_api_key / invalid_api_key |
Kein Schlüssel oder ein falscher. |
403 restricted_api_key |
Die Berechtigung oder der Geltungsbereich des Schlüssels erlaubt dies nicht. |
403 forbidden |
Ihre Rolle oder Ihr Schlüssel erlaubt diese Aktion nicht. |
403 plan_limit_reached |
Sie haben ein Limit Ihres Tarifs erreicht. Siehe Tarife und Limits. |
403 sending_paused |
Der Versand ist pausiert, weil Ihre Bounce- oder Beschwerderate zu hoch ist. |
404 not_found |
Der Endpunkt oder das Angeforderte existiert nicht. |
409 invalid_idempotent_request |
Der Idempotenz-Schlüssel wurde mit einem anderen Payload verwendet. |
415 |
Der Body ist nicht application/json. |
422 validation_error |
Die Anfrage ist ungültig. Die Meldung nennt den Grund. |
422 all_recipients_suppressed |
Jeder Empfänger ist gesperrt oder abgemeldet. Siehe Sperrliste. |
429 rate_limit_exceeded |
Zu viele Anfragen. |
429 daily_quota_exceeded / monthly_quota_exceeded |
Das Sendekontingent Ihres Tarifs ist aufgebraucht. Siehe Tarife und Limits. |
503 service_unavailable |
Der Statistikspeicher hat nicht geantwortet. Der Versand ist nicht betroffen. |
Jedes 429 trägt einen retry-after-Header: die Sekunden, die Sie warten müssen.
Jede Antwort, ob Fehler oder nicht, trägt einen x-request-id-Header: die ID der Anfrage, dieselbe ID, die die Anfrage auf der Seite „Logs“ des Dashboards hat. Nennen Sie sie, wenn Sie uns zu einer Anfrage fragen.
Ein Empfänger, dessen Domain nie E-Mails empfangen kann, etwa x@example.com, x@foo.test oder x@gmail.con, wird mit 422 validation_error abgelehnt. Dasselbe gilt für einen neuen Kontakt mit einer solchen Adresse. Um zu testen, ohne jemandem zu schreiben, senden Sie an success@simulator.amazonses.com.
Empfang, Postfächer und Agent-Sicherheit bringen eigene Fehler mit, die diese Seiten auflisten.
Ratenlimits
Jeder API-Schlüssel kann 600 Anfragen pro Minute stellen, die Schlüssel eines Teams zusammen 3.000. Über dem Limit erhalten Sie 429 rate_limit_exceeded und einen retry-after-Header. Mehr als 20 fehlgeschlagene Authentifizierungen pro Minute von einer IP-Adresse werden auf dieselbe Weise abgelehnt.
Idempotenz
POST /emails und POST /emails/batch akzeptieren einen Idempotency-Key-Header mit 1 bis 256 Zeichen. Das gilt auch für Antworten, Weiterleitungen und Entwurfsversand bei Postfächern sowie für Antworten und Weiterleitungen empfangener E-Mails. Wiederholen Sie die Anfrage mit demselben Schlüssel und demselben Payload, erhalten Sie die ursprüngliche Antwort statt einer zweiten E-Mail. Derselbe Schlüssel mit einem anderen Payload antwortet mit 409.
Paginierung
Listenendpunkte akzeptieren limit (1 bis 100, Standard 20) und die Cursor after und before, jeweils eine Element-ID aus einer früheren Seite. Die Antwort enthält has_more. Listen laufen von neu nach alt:
afternimmt die letzte ID einer Seite und liefert ältere Elemente.beforenimmt die erste ID und liefert neuere Elemente.
Um sich über Neues auf den Stand zu bringen, übergeben Sie die neueste gespeicherte ID als before.
Einige Listen laufen in anderer Reihenfolge, was ihre Referenzseiten angeben: Postfach-Threads (letzte Aktivität zuerst), E-Mails eines Threads (älteste zuerst) sowie Themen und Labels (älteste zuerst, alle auf einmal). Ein Cursor, der auf kein Element passt, antwortet mit 422 validation_error (404 unter /inboxes).
Gut zu wissen
- Anhänge akzeptieren nur Inline-Base64-
content. Eine entferntepath-URL antwortet mit422. Anhänge ergeben zusammen bis zu 10 MiB pro E-Mail, und die gesamte E-Mail muss unter 40 MB bleiben. Programme und Skripte (.exe,.js,.batund Ähnliches, auch innerhalb einer ZIP-Datei) werden immer abgelehnt. Bei einem neuen Team werden einige riskante Typen, etwa Archive, Webseiten und Office-Dateien mit Makros, angenommen, warten aber vor dem Versand auf eine Prüfung. - Kontakte gehören zum Team. Es gibt keine Audiences: Die Audience-Endpunkte funktionieren als Aliase für Segmente.
- Abmeldungen gehören zur Absenderdomain. Siehe Abmeldungen.
- Empfänger:
to,ccundbcczusammen nehmen bis zu 50 Adressen auf, jede ein einzelnes Postfach. Ein Versand, bei dem jedeto-Adresse gesperrt ist, antwortet mit422 all_recipients_suppressed. - Header unterliegen einer Positivliste: jeder
X-*-Name (außerX-SES-*undX-BillionSend-*), Threading- und Prioritäts-Header sowie dasList-Unsubscribe-Paar. Alles andere antwortet mit422. - Betreffzeilen dürfen bis zu 998 Zeichen lang sein.
- Zusätzliche Endpunkte:
GET /usage(Tarif, Limits und Nutzung),DELETE /emails/{id}undGET /emails/metrics(Analysen). - Massenoperationen bei Kontakten:
POST /contacts/batchlegt an undPOST /contacts/batch/removelöscht bis zu 1.000 Kontakte in einer Anfrage.include=properties,topicsbei den Kontaktlisten ergänzt die Eigenschaften und Themen jedes Kontakts. - Massenoperationen bei Sperren akzeptieren bis zu 1.000 Adressen pro Anfrage.
- Zusätzliche Status: Newsletter-Versände können
canceledsein. - Empfang und Postfächer sind in der Beta, mit Long-Polling und einem Live-Ereignisstrom für neue E-Mails. Siehe Empfang und Postfächer.
- Nicht unterstützte Einstellungen werden mit
422abgelehnt, statt stillschweigend ignoriert zu werden.
Signierte Download-Links
Empfangene E-Mails tragen Download-Links für die Rohnachricht und ihre Anhänge. Es sind einfache GET-URLs, die keinen API-Schlüssel brauchen, eine Stunde lang gelten und nach Ablauf mit 403 antworten. Fragen Sie die API erneut nach einem neuen Link. Siehe Empfang.