Introduzione all'API
L’API di SpacePost è un’API REST JSON compatibile con l’API di Resend. L’elenco completo degli endpoint è nel riferimento API, generato dalla specifica OpenAPI.
URL di base
Sezione intitolata “URL di base”https://api.spacepost.devI percorsi sono alla radice (/emails, /domains, …). È accettato anche il prefisso /v1: https://api.spacepost.dev/v1/emails è lo stesso endpoint. Usa quello che preferisce il tuo client.
Autenticazione
Sezione intitolata “Autenticazione”Invia la tua chiave API come bearer token a ogni richiesta:
curl https://api.spacepost.dev/emails -H "Authorization: Bearer sp_live_YOUR_API_KEY"Le chiavi iniziano con sp_live_. Le chiavi full_access possono usare ogni endpoint; le chiavi sending_access possono solo inviare email, facoltativamente da un solo dominio. Vedi Sicurezza e chiavi API.
| Problema | Risposta |
|---|---|
Nessun header Authorization |
401 missing_api_key |
Chiave sconosciuta, revocata o malformata (comprese le chiavi re_ di Resend) |
403 invalid_api_key |
Chiave sending_access su un endpoint che non invia |
401 restricted_api_key |
Richieste
Sezione intitolata “Richieste”- Invia JSON con
Content-Type: application/json. Un JSON non valido restituisce422 validation_error. - I campi sono in
snake_case(reply_to,scheduled_at). Per comodità, in invio sono accettati anchereplyToescheduledAt. - Gli ID sono stringhe UUIDv7; si ordinano per data di creazione, ed è così che funziona la paginazione.
- I timestamp sono ISO 8601 in UTC (
2026-10-23T14:02:09.512Z). - I campi sconosciuti in una richiesta vengono ignorati.
Risposte
Sezione intitolata “Risposte”Le risposte riuscite sono JSON con stato 200. Le risorse hanno un campo object che ne indica il tipo ("email", "domain", …). Gli elenchi hanno questa forma: { "object": "list", "has_more": false, "data": [] }.
Gli errori hanno sempre la stessa forma:
{ "statusCode": 422, "name": "validation_error", "message": "`to`: Invalid email address" }Vedi Errori per ogni name.
Idempotenza
Sezione intitolata “Idempotenza”POST /emails e POST /emails/batch accettano un header Idempotency-Key (da 1 a 256 caratteri, ricordato per 24 ore): la stessa chiave e lo stesso corpo restituiscono la prima risposta invece di inviare di nuovo. Vedi Chiavi di idempotenza.
Limiti di frequenza
Sezione intitolata “Limiti di frequenza”Per team: 10 richieste al secondo (25 su Scale), restituiti negli header ratelimit-*. Vedi Limiti di frequenza.
Versionamento
Sezione intitolata “Versionamento”L’API segue le strutture attuali di Resend e non usa versioni con data. Apportiamo solo modifiche retrocompatibili agli endpoint esistenti (nuovi campi facoltativi, nuovi campi nelle risposte, nuovi tipi di evento e nomi di errore), quindi scrivi client che ignorano i campi sconosciuti e gestiscono nomi di errore sconosciuti. Qualsiasi modifica incompatibile verrebbe rilasciata sotto un nuovo prefisso di percorso con preavviso nel changelog.
L’API invia header CORS permissivi in modo che gli esploratori di API possano chiamarla, ma non chiamarla mai da un browser con una chiave reale. Le chiavi appartengono ai server.