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.

TypeNomValeur
CNAMEzenAAAAMM._domainkey.votredomaine.com<jeton>.dkim.zenoses.comObligatoire : un seul enregistrement, qui prouve la propriété du domaine et active DKIM en une fois.
TXTvotredomaine.comv=spf1 include:spf.zenoses.com ~allRecommandé (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.comv=DMARC1; p=none; rua=mailto:dmarc@votredomaine.comRecommandé
MXbounce.votredomaine.com10 mta1.zenoses.comRecommandé (MAIL FROM personnalisé)
TXTbounce.votredomaine.comv=spf1 include:spf.zenoses.com -allRecommandé

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ètreValeur
Serveursmtp.zenoses.com
Ports587 (STARTTLS) · 465 (TLS implicite)
AuthentificationPLAIN / LOGIN
Utilisateurzenoses (valeur fixe, comme apikey chez d'autres services)
Mot de passevotre 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

CodeSignificationQue faire
250Message accepté (en file d'envoi)—
535 / 530Clé invalide / authentification requiseVérifier la clé (non révoquée)
550 5.7.1From absent, ou domaine non autorisé pour ce compteVérifier le domaine dans l'espace client
553 5.1.3Adresse destinataire invalideCorriger l'adresse
554 5.7.1Envoi en pause (réputation), jeu de configuration inconnu ou désactivéContacter le support ; ne pas réessayer en boucle
454 4.7.0Plafond d'envoi sur 24 h atteintRéessayer plus tard ou demander une hausse
450 4.7.1Débit maximal dépasséRalentir puis réessayer
451 4.3.xErreur temporaireRé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.