Introduction à l'API
L’API SpacePost est une API REST JSON compatible avec l’API Resend. La liste complète des endpoints se trouve dans la référence de l’API, générée à partir de la spécification OpenAPI.
URL de base
Section intitulée « URL de base »https://api.spacepost.devLes chemins sont à la racine (/emails, /domains, …). Un préfixe /v1 est aussi accepté : https://api.spacepost.dev/v1/emails est le même endpoint. Utilisez celui que préfère votre client.
Authentification
Section intitulée « Authentification »Envoyez votre clé API comme jeton bearer à chaque requête :
curl https://api.spacepost.dev/emails -H "Authorization: Bearer sp_live_YOUR_API_KEY"Les clés commencent par sp_live_. Les clés full_access peuvent utiliser tous les endpoints ; les clés sending_access ne peuvent qu’envoyer des e-mails, éventuellement depuis un seul domaine. Voir Sécurité et clés API.
| Problème | Réponse |
|---|---|
Aucun en-tête Authorization |
401 missing_api_key |
Clé inconnue, révoquée ou mal formée (y compris les clés Resend re_) |
403 invalid_api_key |
Clé sending_access sur un endpoint qui n’envoie pas |
401 restricted_api_key |
Requêtes
Section intitulée « Requêtes »- Envoyez du JSON avec
Content-Type: application/json. Un JSON invalide renvoie422 validation_error. - Les champs sont en
snake_case(reply_to,scheduled_at). Par commodité,replyToetscheduledAtsont aussi acceptés à l’envoi. - Les ID sont des chaînes UUIDv7 ; ils se trient par date de création, ce qui fonde la pagination.
- Les horodatages sont en ISO 8601 UTC (
2026-10-23T14:02:09.512Z). - Les champs inconnus dans une requête sont ignorés.
Réponses
Section intitulée « Réponses »Les réponses réussies sont du JSON avec le statut 200. Les ressources portent un champ object qui nomme leur type ("email", "domain", …). Les listes ressemblent à { "object": "list", "has_more": false, "data": [] }.
Les erreurs ont toujours la même forme :
{ "statusCode": 422, "name": "validation_error", "message": "`to`: Invalid email address" }Voir Erreurs pour chaque name.
Idempotence
Section intitulée « Idempotence »POST /emails et POST /emails/batch acceptent un en-tête Idempotency-Key (de 1 à 256 caractères, mémorisé 24 heures) : la même clé avec le même corps renvoie la première réponse au lieu de renvoyer l’e-mail. Voir Clés d’idempotence.
Limites de débit
Section intitulée « Limites de débit »Par équipe : 10 requêtes par seconde (25 sur Scale), indiquées dans les en-têtes ratelimit-*. Voir Limites de débit.
Gestion des versions
Section intitulée « Gestion des versions »L’API suit les formats actuels de Resend et n’utilise pas de versions datées. Nous ne faisons que des changements rétrocompatibles sur les endpoints existants (nouveaux champs facultatifs, nouveaux champs dans les réponses, nouveaux types d’événements et noms d’erreur) : écrivez donc des clients qui ignorent les champs inconnus et gèrent les noms d’erreur inconnus. Tout changement cassant serait publié sous un nouveau préfixe de chemin, avec un préavis dans le changelog.
L’API envoie des en-têtes CORS permissifs pour que les explorateurs d’API puissent l’appeler, mais ne l’appelez jamais depuis un navigateur avec une vraie clé. Les clés doivent rester sur les serveurs.