API

Référence de l'API REST

Tous les endpoints, paramètres, exemples de requêtes et de réponses. Authentification : clé API (Bearer).

Exemple rapide

curl https://api.sendnomi.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Welcome",
    "html": "<h1>Hello!</h1>"
  }'

La clé API s'obtient depuis le panneau → onglet Développeur. Nous recommandons des clés distinctes, à portée limitée, pour les environnements de production et de test.

Authentification

Chaque requête porte un en-tête Authorization: Bearer YOUR_API_KEY. Les clés sont créées dans le panneau, affichées une seule fois à la création, puis hachées. Si vous perdez une clé, vous en générez une nouvelle et révoquez l'ancienne — la clé révoquée est désactivée à l'instant même.

  • Permissions par portée : 30 portées (send · campaign · template · webhook · domain · ...). Une clé n'accède qu'aux zones que vous autorisez.
  • Liste blanche d'IP : vous pouvez restreindre les clés de production à des plages IP/CIDR spécifiques.
  • Limite de durée : vous pouvez attribuer un TTL aux clés ; elles expirent automatiquement à l'échéance.
  • Journal d'audit : chaque utilisation de clé est consignée avec horodatage + endpoint + résultat.

Idempotency-Key

Utilisez l'en-tête Idempotency-Key sur les requêtes POST — une seconde requête avec la même clé renvoie à nouveau la première réponse, sans envoi en double. UUIDv4 recommandé ; la clé est conservée 24 heures. 

curl https://api.sendnomi.com/v1/messages \
  -H "Authorization: Bearer sn_live_•••" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-..." \
  ...

Format des erreurs

Toutes les réponses d'erreur partagent la même enveloppe — code + message + détail propre à la requête :

{
  "error": {
    "code":    "invalid_recipient",
    "message": "Recipient address does not match the format rule",
    "field":   "to",
    "request_id": "req_01HX8K..."
  }
}

Les codes de statut HTTP suivent la RFC 7231. Les erreurs temporaires sont en 5xx + retry-after ; les erreurs permanentes en 4xx ne font pas l'objet de nouvelles tentatives.

Limite de débit

La limite dépend de votre plan et s'affiche en temps réel dans le panneau. Chaque réponse inclut les en-têtes :

  • X-RateLimit-Limit · requêtes autorisées dans la fenêtre
  • X-RateLimit-Remaining · quota de requêtes restant
  • X-RateLimit-Reset · moment de réinitialisation de la fenêtre (epoch Unix)

Si vous recevez un 429, patientez pendant la durée indiquée dans l'en-tête Retry-After. Les SDK le font automatiquement.

Gestion des versions

La version est obligatoire dans l'URL (/v1/). Le passage à une nouvelle version s'accompagne d'une fenêtre de dépréciation de 12 mois + d'un avis dans le changelog. Les changements cassants ne sont jamais déployés en silence — dès qu'un endpoint déprécié est utilisé, un en-tête d'avertissement est renvoyé.

Liste des endpoints

  • POST /v1/messages Envoyer un e-mail unique ou en masse.
  • GET /v1/messages/{id} Consulter le statut d’un message donné.
  • GET /v1/messages Liste des messages, avec filtrage et pagination.
  • POST /v1/templates Créer un nouveau modèle (mix Handlebars + Liquid).
  • GET /v1/templates/{id} Détail du modèle.
  • POST /v1/suppressions Ajouter une adresse à la liste de suppression.
  • GET /v1/suppressions Liste de suppression.
  • POST /v1/webhooks Enregistrer un endpoint de webhook.
  • GET /v1/events Flux d’événements (envoyé, remis, ouvert, cliqué, rebondi, plainte).
  • GET /v1/domains Vos domaines vérifiés.

Spécification OpenAPI 3.1 : /v1/openapi.json — pour import IDE / Postman. Chaque endpoint est documenté avec l'ensemble de ses paramètres, un exemple de requête et le schéma de réponse.