Documentation
Dernière mise à jour : 15 octobre 2026
Tout ce qu'il faut pour envoyer votre premier e-mail et suivre ses résultats. L'accès se demande sur le formulaire.
1. Vérifier votre domaine
Dans l'espace client, ajoutez votre domaine : zenoses génère un enregistrement à créer chez votre hébergeur DNS (votredomaine.com ci-dessous). Les valeurs exactes sont affichées dans l'espace client.
| Type | Nom | Valeur | |
|---|---|---|---|
| CNAME | zenAAAAMM._domainkey.votredomaine.com | <jeton>.dkim.zenoses.com | Obligatoire : un seul enregistrement, qui prouve la propriété du domaine et active DKIM en une fois. |
| TXT | votredomaine.com | v=spf1 include:spf.zenoses.com ~all | Recommandé (SPF) : si un SPF existe déjà, ajoutez-y seulement include:spf.zenoses.com. N'est pas nécessaire pour activer l'envoi. |
| TXT | _dmarc.votredomaine.com | v=DMARC1; p=none; rua=mailto:dmarc@votredomaine.com | Recommandé |
| MX | bounce.votredomaine.com | 10 mta1.zenoses.com | Recommandé (MAIL FROM personnalisé) |
| TXT | bounce.votredomaine.com | v=spf1 include:spf.zenoses.com -all | Recommandé |
Si votre hébergeur DNS refuse un CNAME à cet endroit (certains gabarits de domaine racine l'interdisent), l'espace client affiche aussi la valeur TXT complète en solution de repli : elle remplace le CNAME, on ne publie pas les deux.
Cliquez ensuite sur « Vérifier » : l'envoi est activé dès que la propriété, DKIM et SPF sont validés. Un seul enregistrement SPF est autorisé par domaine.
2. Récupérer votre clé
Créez une clé dans l'espace client (menu « Clés »). Elle commence par zk_ et n'est affichée qu'une fois : copiez-la tout de suite. Vous pouvez la révoquer à tout moment.
3. Bac à sable (nouveaux comptes)
À l'ouverture, votre compte est en bac à sable : vous ne pouvez écrire qu'à des adresses de test que vous confirmez (menu « Bac à sable » de l'espace client ; chaque adresse reçoit un lien de confirmation). Un envoi vers une adresse non confirmée est refusé (550). C'est la même logique qu'AWS SES : cela protège la réputation d'envoi le temps de valider votre intégration. Demandez le passage en production à contact@zenoses.com pour écrire à n'importe quelle adresse.
3. Envoyer par SMTP
| Paramètre | Valeur |
|---|---|
| Serveur | smtp.zenoses.com |
| Ports | 587 (STARTTLS) · 465 (TLS implicite) |
| Authentification | PLAIN / LOGIN |
| Utilisateur | zenoses (valeur fixe, comme apikey chez d'autres services) |
| Mot de passe | votre clé zk_… |
L'adresse From doit appartenir à un domaine vérifié de votre compte.
cURL
curl --url 'smtp://smtp.zenoses.com:587' --ssl-reqd \ --mail-from 'noreply@votredomaine.com' --mail-rcpt 'client@exemple.com' \ --user 'zenoses:zk_votre_cle' -T message.eml
Python
import smtplib, ssl from email.message import EmailMessage m = EmailMessage() m["From"] = "Votre App" m["To"] = "client@exemple.com" m["Subject"] = "Bonjour" m["X-Zenoses-Configuration-Set"] = "transactionnel" # facultatif m.set_content("Texte du message") with smtplib.SMTP("smtp.zenoses.com", 587) as s: s.starttls(context=ssl.create_default_context()) s.login("zenoses", "zk_votre_cle") s.send_message(m)
Node.js (nodemailer)
const nodemailer = require("nodemailer");
const t = nodemailer.createTransport({
host: "smtp.zenoses.com", port: 587, secure: false, requireTLS: true,
auth: { user: "zenoses", pass: "zk_votre_cle" },
});
await t.sendMail({ from: "noreply@votredomaine.com", to: "client@exemple.com", subject: "Bonjour", text: "Texte du message" });
4. Jeux de configuration
Un jeu de configuration regroupe vos envois (par exemple « transactionnel » et « marketing ») pour séparer les statistiques et cibler des webhooks. Ajoutez l'en-tête suivant à vos messages ; il est retiré avant l'envoi au destinataire :
X-Zenoses-Configuration-Set: transactionnel
5. Réponses et erreurs SMTP
| Code | Signification | Que faire |
|---|---|---|
| 250 | Message accepté (en file d'envoi) | — |
| 535 / 530 | Clé invalide / authentification requise | Vérifier la clé (non révoquée) |
| 550 5.7.1 | From absent, ou domaine non autorisé pour ce compte | Vérifier le domaine dans l'espace client |
| 553 5.1.3 | Adresse destinataire invalide | Corriger l'adresse |
| 554 5.7.1 | Envoi en pause (réputation), jeu de configuration inconnu ou désactivé | Contacter le support ; ne pas réessayer en boucle |
| 454 4.7.0 | Plafond d'envoi sur 24 h atteint | Réessayer plus tard ou demander une hausse |
| 450 4.7.1 | Débit maximal dépassé | Ralentir puis réessayer |
| 451 4.3.x | Erreur temporaire | Réessayer avec un délai croissant |
Les codes 4xx sont temporaires (réessayez) ; les codes 5xx sont définitifs (ne réessayez pas sans corriger).
6. Webhooks
Créez un webhook dans l'espace client : une URL HTTPS (les adresses internes sont refusées) et les événements voulus, éventuellement limités à un jeu de configuration. Types : Send, Delivery, Bounce, Complaint, Reject, DeliveryDelay. Répondez par un code 2xx en moins de 8 secondes.
Exemple de notification
{
"eventType": "Bounce",
"id": "48213",
"timestamp": "2026-10-15T12:31:07+00:00",
"mail": { "messageId": "7f3a9c01b2e4", "destination": ["client@exemple.com"],
"sendingDomain": "votredomaine.com", "configurationSet": "transactionnel", "tenantId": 12 },
"bounce": { "bounceType": "Permanent",
"bouncedRecipients": [{ "emailAddress": "client@exemple.com", "status": "5.1.1", "diagnosticCode": "550 5.1.1 user unknown" }] }
}
En-têtes
X-Zenoses-Signature: t=<horodatage>,v1=<hex> · X-Zenoses-Event-Type · X-Zenoses-Event-Id · X-Zenoses-Delivery-Id
Vérifier la signature
La signature est un HMAC-SHA256 de "<t>." + corps brut avec le secret whsec_… du webhook. Vérifiez-la sur le corps brut, avant de parser le JSON :
import hmac, hashlib, time
def verify(secret: str, header: str, body: bytes, tolerance=300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t, v1 = parts["t"], parts["v1"]
if abs(time.time() - int(t)) > tolerance: # rejeu
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
Réessais
En cas d'échec, zenoses réessaie après 1 min, 5 min, 30 min, 2 h puis 6 h, puis abandonne cette livraison. Un webhook qui échoue 20 fois de suite est désactivé automatiquement (vous êtes alerté).
7. Liste de suppression
Les adresses qui rebondissent définitivement ou se plaignent sont ajoutées automatiquement à votre liste de suppression : les envois suivants vers ces adresses sont ignorés (si toutes les adresses d'un message sont supprimées, il est accepté mais rien n'est envoyé). Vous pouvez importer, exporter et gérer la liste dans l'espace client.
8. Plafonds et réputation
Votre compte démarre avec des plafonds prudents (volume par 24 h et débit par seconde) qui augmentent avec la qualité de votre trafic. Si les rebonds ou les plaintes dépassent les seuils (rebonds : alerte à 5 %, pause à 10 % ; plaintes : alerte à 0,1 %, pause à 0,5 %), le domaine ou le compte est mis en pause automatiquement. Voir la politique d'usage acceptable.
9. API HTTPS bientôt
Une API HTTPS d'envoi (avec modèles à variables {{nom}} et envoi en masse) (authentification par clé zk_… en Authorization: Bearer) est en cours d'ouverture. En attendant, utilisez SMTP, qui offre les mêmes plafonds et les mêmes protections.