Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

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 /emails antwortet mit 403 restricted_api_key, ebenso GET /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:

  • after nimmt die letzte ID einer Seite und liefert ältere Elemente.
  • before nimmt 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 entfernte path-URL antwortet mit 422. 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, .bat und Ä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, cc und bcc zusammen nehmen bis zu 50 Adressen auf, jede ein einzelnes Postfach. Ein Versand, bei dem jede to-Adresse gesperrt ist, antwortet mit 422 all_recipients_suppressed.
  • Header unterliegen einer Positivliste: jeder X-*-Name (außer X-SES-* und X-BillionSend-*), Threading- und Prioritäts-Header sowie das List-Unsubscribe-Paar. Alles andere antwortet mit 422.
  • Betreffzeilen dürfen bis zu 998 Zeichen lang sein.
  • Zusätzliche Endpunkte: GET /usage (Tarif, Limits und Nutzung), DELETE /emails/{id} und GET /emails/metrics (Analysen).
  • Massenoperationen bei Kontakten: POST /contacts/batch legt an und POST /contacts/batch/remove löscht bis zu 1.000 Kontakte in einer Anfrage. include=properties,topics bei 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 canceled sein.
  • 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 422 abgelehnt, statt stillschweigend ignoriert zu werden.

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.

War diese Seite hilfreich?