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), publiez 3 types d'enregistrements DNS chez votre hébergeur : SPF, DKIM et DMARC. Ajoutez d'abord votre domaine dans Réglages → Expéditeurs : Envol génère alors vos 3 enregistrements DKIM personnalisé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. Connectez-vous à hPanel, ouvrez Domaines puis cliquez sur votre domaine.
2. Allez dans DNS / Serveurs de noms → section Gérer les enregistrements DNS.
3. SPF — Type TXT, Nom @, Valeur v=spf1 include:mail.envol.email ~all. Si un SPF existe déjà, n'en créez pas un second : ajoutez include:mail.envol.email dans l'existant.
4. DMARC — Type TXT, Nom _dmarc, Valeur v=DMARC1; p=none; rua=mailto:dmarc@votre-domaine.fr.
5. DKIM (×3) — Pour chacune des 3 lignes affichées dans Envol (Réglages → Expéditeurs) : Type CNAME, Nom = la partie hôte sans le domaine, Valeur = la cible fournie.
6. Enregistrez, patientez 5 à 30 min, puis revenez dans Envol et cliquez sur Vérifier.

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.