Einführung in die API
Die SpacePost-API ist eine JSON-REST-API, die mit der Resend-API kompatibel ist. Die vollständige Liste der Endpoints steht in der API-Referenz, die aus der OpenAPI-Spezifikation generiert wird.
Basis-URL
Abschnitt betitelt „Basis-URL“https://api.spacepost.devPfade liegen im Root (/emails, /domains, …). Ein Präfix /v1 wird ebenfalls akzeptiert: https://api.spacepost.dev/v1/emails ist derselbe Endpoint. Verwende, was dein Client bevorzugt.
Authentifizierung
Abschnitt betitelt „Authentifizierung“Sende deinen API-Schlüssel bei jeder Anfrage als Bearer-Token:
curl https://api.spacepost.dev/emails -H "Authorization: Bearer sp_live_YOUR_API_KEY"Schlüssel beginnen mit sp_live_. full_access-Schlüssel können jeden Endpoint nutzen; sending_access-Schlüssel können nur E-Mails senden, optional von einer Domain. Siehe Sicherheit und API-Schlüssel.
| Problem | Antwort |
|---|---|
Kein Authorization-Header |
401 missing_api_key |
Unbekannter, widerrufener oder fehlerhafter Schlüssel (einschließlich re_-Schlüssel von Resend) |
403 invalid_api_key |
sending_access-Schlüssel an einem Endpoint, der nicht zum Senden dient |
401 restricted_api_key |
Anfragen
Abschnitt betitelt „Anfragen“- Sende JSON mit
Content-Type: application/json. Ungültiges JSON liefert422 validation_error. - Felder sind
snake_case(reply_to,scheduled_at). Der Einfachheit halber werden beim Senden auchreplyToundscheduledAtakzeptiert. - IDs sind UUIDv7-Strings; sie sortieren nach Erstellungszeit, so funktioniert die Paginierung.
- Zeitstempel sind ISO 8601 in UTC (
2026-10-23T14:02:09.512Z). - Unbekannte Felder in einer Anfrage werden ignoriert.
Antworten
Abschnitt betitelt „Antworten“Erfolgreiche Antworten sind JSON mit dem Status 200. Ressourcen tragen ein Feld object, das ihren Typ nennt ("email", "domain", …). Listen sehen aus wie { "object": "list", "has_more": false, "data": [] }.
Fehler haben immer dieselbe Form:
{ "statusCode": 422, "name": "validation_error", "message": "`to`: Invalid email address" }Jeden name findest du unter Fehler.
Idempotenz
Abschnitt betitelt „Idempotenz“POST /emails und POST /emails/batch akzeptieren einen Header Idempotency-Key (1 bis 256 Zeichen, 24 Stunden lang gespeichert): Derselbe Schlüssel mit demselben Body liefert die erste Antwort, statt erneut zu senden. Siehe Idempotenz-Schlüssel.
Rate Limits
Abschnitt betitelt „Rate Limits“Pro Team: 10 Anfragen pro Sekunde (25 bei Scale), zurückgegeben in ratelimit-*-Headern. Siehe Rate Limits.
Versionierung
Abschnitt betitelt „Versionierung“Die API folgt den aktuellen Formaten von Resend und verwendet keine datierten Versionen. An bestehenden Endpoints nehmen wir nur abwärtskompatible Änderungen vor (neue optionale Felder, neue Felder in Antworten, neue Event-Typen und Fehlernamen). Schreibe daher Clients, die unbekannte Felder ignorieren und unbekannte Fehlernamen behandeln. Alles, was Inkompatibilitäten mit sich bringt, würde unter einem neuen Pfadpräfix erscheinen, mit Vorankündigung im Changelog.
Die API sendet großzügige CORS-Header, damit API-Explorer sie aufrufen können, doch rufe sie nie mit einem echten Schlüssel aus einem Browser auf. Schlüssel gehören auf Server.