API REST SendAs.me

L'API REST SendAs.me permet de gérer programmatiquement toutes vos ressources : applications, connexions OAuth, webhooks, logs et facturation.

URL de base

L'URL de base de l'API est configurée via la variable d'environnement API_URL lors du déploiement.

https://api.sendas.me

Toutes les URLs ci-dessous sont relatives à cette base.

Authentification

Chaque requête à l'API doit inclure le header X-Api-Secret avec votre clé d'API :

X-Api-Secret: sk_prod_votre_cle_api_secrete

Sécurité de la clé API

Ne committez jamais votre clé API dans votre code source. Utilisez des variables d'environnement. La clé API donne un accès complet à toutes vos ressources SendAs.me.

Exemple avec cURL

curl https://api.sendas.me/apps \
  -H "X-Api-Secret: sk_prod_votre_cle_api_secrete"

Exemple avec Python

import httpx

API_URL = "https://api.sendas.me"
API_SECRET = "sk_prod_votre_cle_api_secrete"

headers = {"X-Api-Secret": API_SECRET}

async with httpx.AsyncClient() as client:
    response = await client.get(f"{API_URL}/apps", headers=headers)
    data = response.json()

Format des réponses

Toutes les réponses sont au format JSON avec le header Content-Type: application/json.

Réponse de succès

Les réponses de succès retournent directement l'objet ou la liste :

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Mon Application",
  "created_at": "2024-01-15T10:30:00Z"
}

Réponse de liste

Les listes sont enveloppées dans un objet avec une clé de contexte :

{
  "apps": [
    { "id": "...", "name": "App 1" },
    { "id": "...", "name": "App 2" }
  ],
  "total": 2
}

Réponse d'erreur

En cas d'erreur, la réponse contient un objet detail :

{
  "detail": "Application not found"
}

Ou, pour les erreurs de validation (422) :

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Codes HTTP

Code	Signification
200 OK	Requête réussie
201 Created	Ressource créée avec succès
204 No Content	Opération réussie sans corps de réponse (suppression)
400 Bad Request	Requête malformée
401 Unauthorized	Header X-Api-Secret absent ou invalide
403 Forbidden	Accès refusé à cette ressource
404 Not Found	Ressource introuvable
409 Conflict	Conflit (ex: ressource déjà existante)
422 Unprocessable Entity	Erreur de validation des données
429 Too Many Requests	Rate limiting dépassé
500 Internal Server Error	Erreur serveur interne

Rate Limiting

L'API applique un rate limiting pour protéger le service :

Type	Limite
Requêtes globales	1000 req / heure / tenant
Création d'application	10 / heure
Reset mot de passe SMTP	5 / heure / application
OAuth connect	20 / heure

Lorsque la limite est dépassée, l'API retourne un 429 Too Many Requests avec le header Retry-After indiquant le délai en secondes.

Pagination

Les endpoints qui retournent des listes supportent la pagination via les paramètres :

Paramètre	Type	Défaut	Description
limit	integer	20	Nombre d'éléments par page (max: 100)
offset	integer	0	Décalage pour la pagination

Exemple :

curl "https://api.sendas.me/logs?limit=50&offset=100" \
  -H "X-Api-Secret: ..."

Versioning

L'API actuelle est à la version v1. Le versioning est intégré à l'URL de base. Les changements non rétrocompatibles seront publiés sur /v2/ avec une période de dépréciation de 6 mois.

Endpoints disponibles

Méthode	Endpoint	Description
GET	/me	Informations du tenant courant
GET	/stats	Statistiques globales
GET	/email-stats	Statistiques d'envoi mensuelles
GET	/logs	Logs des e-mails
GET	/apps	Liste des applications
POST	/apps	Créer une application
GET	/apps/{pushable_key}	Détails d'une application
PUT	/apps/{pushable_key}	Modifier une application
DELETE	/apps/{pushable_key}	Supprimer une application
POST	/apps/{pushable_key}/reset-smtp-password	Réinitialiser le mot de passe SMTP
GET	/oauth/connect/{app_id}	Initier la connexion OAuth
GET	/oauth/callback/{plugin}	Callback OAuth (Google/Microsoft)
GET	/stripe/subscription	Détails de l'abonnement Stripe
POST	/stripe/checkout-setup	Créer une session Stripe Checkout
POST	/stripe/cancel-subscription	Annuler l'abonnement