RÉFÉRENCE API

Envoyer un email

POST /v1/emails accepte l'envoi et répond immédiatement : la distribution effective est traitée en file d'attente, avec relances automatiques en cas d'échec temporaire.

POST/v1/emails— authentifié par clé API (Authorization: Bearer zd_live_…)

Paramètres du corps

Nom	Type	Requis	Description
`from`	string	Oui	Expéditeur. « adresse@domaine » ou « Nom <adresse@domaine> ». Le domaine doit être un domaine vérifié de votre compte.
`to`	string	Oui	Destinataire — une seule adresse nue (« client@exemple.gn »), sans nom affiché. Pas de liste ni de séparateur en v1.
`subject`	string	Oui	Sujet de l'email. Entre 1 et 300 caractères.
`html`	string	Non*	Corps HTML de l'email. Limité à 500 Ko (mesurés en octets UTF-8).
`text`	string	Non*	Corps texte brut de l'email. Limité à 500 Ko (mesurés en octets UTF-8).

* Au moins l’un des deux champs html ou text est obligatoire.

Exemple de requête

curl

curl -X POST https://api.zendou.dev/v1/emails \
  -H "Authorization: Bearer zd_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Boutique Awa <no-reply@boutique-awa.gn>",
    "to": "cliente@exemple.gn",
    "subject": "Votre commande est confirmée",
    "html": "<p>Merci pour votre commande, elle est en préparation.</p>"
  }'

Exemple de réponse

Toute requête acceptée répond 202 Accepted — y compris quand le destinataire est bloqué : l’email est alors tracé avec le statut suppressed, sans être mis en file ni facturé.

202 Accepted — mis en file

{
  "id": "e_7f3a91c2b8d1",
  "status": "queued"
}

202 Accepted — adresse supprimée

{
  "id": "e_1a2b3c4d5e6f",
  "status": "suppressed"
}

Codes d’erreur

Code	Cas	Message renvoyé	Marche à suivre
400	Adresse d'expédition illisible	« L'adresse d'expédition est invalide : utilisez « adresse@domaine » ou « Nom <adresse@domaine> ». »	Corrigez le format du champ from.
400	Adresse destinataire illisible	« L'adresse du destinataire est invalide : indiquez une seule adresse comme « client@exemple.gn ». »	Le champ to n'accepte qu'une seule adresse nue, sans nom affiché.
400	Sujet vide ou trop long	« Le sujet est obligatoire et ne doit pas dépasser 300 caractères. »	Renseignez subject avec 1 à 300 caractères.
400	Ni html ni text fourni	« Fournissez au moins un contenu : « html » ou « text ». »	Ajoutez au moins l'un des deux champs dans le corps de la requête.
400	Contenu trop volumineux	« Chaque contenu (« html », « text ») est limité à 500 Ko. »	Réduisez la taille du contenu — par exemple en hébergeant les images à part plutôt qu'en base64 inline.
401	Clé API absente, inconnue ou révoquée	« Clé API invalide ou révoquée »	Vérifiez l'en-tête Authorization: Bearer zd_live_…. Générez une nouvelle clé si nécessaire.
402	Solde de crédits insuffisant	« Crédits insuffisants : rechargez votre compte pour continuer à envoyer. »	Rechargez votre solde (voir Facturation).
403	Domaine d'envoi non vérifié	« Le domaine d'envoi n'est pas vérifié : ajoutez-le à votre compte et validez ses enregistrements DNS avant d'envoyer. »	Suivez le guide de vérification de domaine avant de réessayer.
403	Compte suspendu	« Ce compte est suspendu »	Le compte a été suspendu automatiquement pour protéger la réputation d'envoi (taux de rebonds ou de plaintes trop élevé). Contactez le support.
429	Limite journalière atteinte	« Limite journalière atteinte : réessayez demain ou demandez une augmentation de quota. »	Réessayez le lendemain (minuit UTC) — la limite augmente automatiquement avec l'ancienneté et le volume du compte.

Voir Erreurs pour la référence complète de tous les codes HTTP de l’API, toutes routes confondues.

Statuts d’un email

Un envoi accepté suit normalement le cycle QUEUED → SENT → DELIVERED. Les statuts suivants marquent une sortie de ce cycle :

Statut	Signification
QUEUED	L'email a été accepté et débité d'un crédit. Il attend d'être traité par la file d'envoi.
SENT	L'email a été remis à Amazon SES pour distribution.
DELIVERED	Le serveur du destinataire a confirmé la réception. Fin normale du cycle.
BOUNCED	Le message a rebondi. Un rebond dur (adresse inexistante) ajoute automatiquement l'adresse à votre liste de suppression ; un rebond transitoire (boîte pleine, serveur indisponible) est seulement enregistré.
COMPLAINED	Le destinataire a signalé l'email comme spam. L'adresse est ajoutée automatiquement à la liste de suppression.
SUPPRESSED	L'envoi a été bloqué avant la mise en file car l'adresse est sur une liste de suppression (la vôtre ou globale à la plateforme). Non facturé.
REJECTED / FAILED	L'email n'a pas pu être délivré : message rejeté par Amazon SES, ou abandon après plusieurs tentatives d'envoi.

Effet sur la réputation

Les rebonds durs et les plaintes alimentent le taux de rebond et de plainte de votre compte, surveillé en continu. Au-delà des seuils tolérés, le compte est suspendu automatiquement pour protéger la délivrabilité de tous les clients Zendou — mieux vaut nettoyer régulièrement ses listes de diffusion que d’atteindre ce seuil.