Documentation Envol

Envoyez vos e-mails transactionnels par API (confirmation de commande, réinitialisation de mot de passe, code de connexion, facture…), écoutez les événements en temps réel via webhooks, et authentifiez votre domaine pour atterrir en boîte de réception. Tout ce dont vous avez besoin tient sur cette page.

URL de base

Toutes les requêtes se font en HTTPS sur :

https://envolmail.com/api/v1

Authentification

Chaque requête est authentifiée par une clé API passée dans l'en-tête Authorization, au format Bearer. Vos clés commencent par env_live_.

Authorization: Bearer env_live_VOTRE_CLE

Créer une clé

1. Dans Envol, ouvrez Réglages → Clés API.
2. Cliquez sur Nouvelle clé, donnez-lui un nom (ex. « Production »).
3. Copiez la clé : elle n'est affichée qu'une seule fois. Stockez-la dans une variable d'environnement, jamais dans votre code source.

Envoyer un e-mail

Envoie un e-mail transactionnel. L'adresse from doit être un expéditeur vérifié de votre espace (voir Authentifier votre domaine).

Paramètres

* Vous devez fournir html ou template.

Exemple

curl -X POST https://envolmail.com/api/v1/emails \
  -H "Authorization: Bearer env_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Studio Hirsch <contact@studio-hirsch.fr>",
    "to": "client@example.com",
    "subject": "Votre commande est en route",
    "html": "<h1>Merci !</h1><p>Suivi : FR-90217</p>"
  }'

Templates & variables

Plutôt que d'envoyer du HTML à chaque requête, réutilisez un template enregistré dans Envol et passez seulement les variables. Référencez-le par son nom via template, et fournissez les valeurs dans data. Les variables s'écrivent {{maVariable}} dans le template et l'objet.

{
  "from": "contact@studio-hirsch.fr",
  "to": "client@example.com",
  "subject": "Votre commande {{order}}",
  "template": "order-shipped",
  "data": {
    "order": "FR-90217",
    "tracking": "Colissimo 6A-1180-22"
  }
}

Réponses & erreurs

En cas de succès, l'API renvoie 202 Accepted : l'e-mail est accepté et mis en file d'envoi.

{
  "id": "0113019ea5344f47-7c2b…",
  "status": "accepted"
}

Codes d'erreur

Configurer un webhook

Envol envoie en temps réel les événements de vos envois (ouvertures, clics, rejets…) vers l'URL HTTPS de votre choix. Configurez-la dans Réglages → Webhooks, choisissez les événements à recevoir, et conservez le secret (whsec_…) généré pour vérifier les signatures.

Événements disponibles

Format du payload

Chaque événement est envoyé en POST, corps JSON :

{
  "type": "DELIVERED",
  "messageId": "0113019ea5344f47-7c2b…",
  "email": "client@example.com",
  "meta": {},
  "deliveredAt": "2026-06-08T10:12:30.000Z"
}

Vérifier la signature

Chaque requête porte l'en-tête X-Envol-Signature : un HMAC-SHA256 (en hexadécimal) du corps brut, calculé avec le secret de votre webhook. Recalculez-le de votre côté et comparez, pour garantir que l'événement vient bien d'Envol.

import express from "express";
import crypto from "crypto";

const app = express();

app.post(
  "/webhooks/envol",
  express.raw({ type: "application/json" }), // garder le corps BRUT
  (req, res) => {
    const signature = req.header("X-Envol-Signature");
    const expected = crypto
      .createHmac("sha256", process.env.ENVOL_WEBHOOK_SECRET)
      .update(req.body)        // Buffer non parsé
      .digest("hex");

    if (signature !== expected) return res.status(401).end();

    const event = JSON.parse(req.body.toString());
    // event.type · event.messageId · event.email · event.deliveredAt
    res.status(200).end();
  },
);

Authentifier votre domaine

Pour envoyer depuis votre propre domaine et atterrir en boîte de réception (et non en spam), authentifiez-le avec SPF et DKIM. L'envoi passe par Zoho ZeptoMail : la clé DKIM est générée dans la console ZeptoMail, par domaine.

Le parcours en 3 étapes

1. Console ZeptoMail → Domains → ajoutez votre domaine. ZeptoMail affiche alors les 2 enregistrements exacts à publier : un TXT (DKIM) + un CNAME (retours).
2. Publiez-les chez votre hébergeur DNS (voir les guides par hébergeur ci-dessous), puis revenez les valider dans ZeptoMail.
3. Dans Envol, Réglages → Expéditeurs → ajoutez le même domaine → Vérifier. Envol contrôle que les enregistrements sont bien publiés.

Les enregistrements à publier

Guides par hébergeur

Les étapes exactes selon l'endroit où votre domaine est géré. Sélectionnez votre hébergeur :

1. Récupérez d'abord vos 2 enregistrements (TXT DKIM + CNAME de retours) dans la console ZeptoMail → Domains.
2. Connectez-vous à hPanel → Domaines → votre domaine → DNS / Gérer les enregistrements.
3. DKIM — Type TXT, Nom = le sélecteur fourni (ex. 13182548._domainkey), Valeur = la clé k=rsa; p=… de la console.
4. Retours — Type CNAME, Nom bounce-zem, Cible = clusterNN.zeptomail.com (valeur de la console).
5. DMARC (recommandé) — Type TXT, Nom _dmarc, Valeur v=DMARC1; p=none; rua=mailto:dmarc@votre-domaine.fr.
6. Enregistrez, patientez 5 à 30 min, validez dans ZeptoMail puis cliquez Vérifier dans Envol.

Domaines formulaires & landing pages

Servez vos formulaires (/f/…) et landing pages (/p/…) depuis votre propre sous-domaine (ex. forms.votre-domaine.fr) plutôt que le domaine Envol. Ajoutez le sous-domaine dans Réglages → Domaines, puis publiez un seul enregistrement CNAME.