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_…)

Essayez tout de suite, sans domaine

Pas encore de domaine vérifié ? Zendou fournit une adresse d’expédition de test, prête à l’emploi dès qu’une clé API existe — copiable sur Clés API. Elle n’est pas reproduite ici : ainsi cette page reste toujours exacte, même si Zendou change un jour de domaine d’expédition partagé.

curl — mode bac à sable

curl -X POST https://api.zendou.dev/v1/emails \
  -H "Authorization: Bearer zd_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "adresse affichée sur /dashboard/cles-api",
    "to": "vous@votre-adresse-de-compte.gn",
    "subject": "Mon premier email Zendou",
    "html": "<p>Ça marche déjà, avant même de vérifier un domaine.</p>"
  }'

Une seule limite

Depuis cette adresse, vous ne pouvez écrire qu’à l’adresse email de votre propre compte — largement de quoi tester l’intégration de bout en bout dès aujourd’hui. Vérifiez un domaine quand vous passerez en production, pour écrire à vos utilisateurs.

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	Envoi test vers un autre destinataire que son propre compte	« Depuis l'adresse de test, vous ne pouvez écrire qu'à l'adresse email de votre compte. Vérifiez un domaine pour écrire à vos utilisateurs. »	Envoyez à votre propre adresse de compte, ou vérifiez un domaine pour écrire à vos utilisateurs.
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.