Documentation MailPilotX

Guide complet : parcours produit, envoi, API, intégrations et bonnes pratiques.

Vue d'ensemble

MailPilotX est une plateforme email pour PME et agences : éditeur visuel, campagnes massives, mails transactionnels à la demande, listes de contacts et domaines SMTP (BYO : vous apportez votre serveur d'envoi).

Le parcours recommandé : créer un projet (design) → rattacher listes, domaines, campagnes et mails réutilisables depuis le hub projet → envoyer ou exposer via l'API.

Projets & hub

Un projet = un design email multilingue (blocs, variables, médias). Ouvrez un projet pour accéder au hub : design, campagnes, mails à la demande, listes et domaines filtrés par projet.

Depuis le hub, chaque ressource créée hérite automatiquement du project_id. Le wizard campagne démarre à l'étape Audience avec listes et domaines du projet.

Éditeur : blocs drag & drop, traductions, variables {{…}}, aperçu fusion, export HTML.
Brand kit (onglet Général → Brand) : couleurs, logo et police par défaut pour les nouveaux blocs.
Conditions showWhen : afficher un bloc si une variable correspond à une valeur (ex. plan = premium).
Checklist pré-envoi : liens, poids images, alertes qualité avant export.

Campagnes (envoi massif)

Wizard en 4 étapes : audience (liste ou segment), objet, planification, validation. Tracking ouverture/clic automatique via pixel et liens trackés.

Planification : date/heure, jours autorisés et plage horaire. Un worker vérifie les campagnes scheduled et lance l'envoi dans la fenêtre configurée.

Modes audience : liste unique, listes par langue, segment dynamique.
A/B test : split initial (ex. 10 %), mesure ouvertures/clics, envoi automatique de la variante gagnante au reste.
Stats post-envoi : ouvertures, clics, bounces : accessible depuis Campagnes → Statistiques.
Variable système {{unsubscribe_url}} : lien de désinscription injecté automatiquement si absent du HTML.

Mails à la demande (transactionnels)

Mails réutilisables identifiés par un slug (ex. bienvenue, reset-password). Chaque mail est lié à un projet (design) et optionnellement à un domaine d'envoi.

Envoi depuis l'interface ou via API POST /api/v1/transactional-emails/send avec slug, destinataire et variables.

Tracking open/click dédié (routes /api/track/t/…).
Stats par template : taux d'ouverture et de clic dans Mails à la demande.
Réponse API asynchrone (202) : l'envoi passe par la file send_jobs ; le send_id permet le suivi.
Clés API test (mpx_test_…) : envoi simulé sans SMTP réel, status simulated.

POST /api/v1/transactional-emails/send
Authorization: Bearer mpx_live_…

{
  "slug": "bienvenue",
  "to": "client@example.com",
  "name": "Marie",
  "variables": { "prenom": "Marie", "code": "ABC123" }
}

File d'envoi & fiabilité

Par défaut (SEND_VIA_JOBS=1), campagnes et transactionnels passent par la table send_jobs. Un worker Node traite les jobs avec retries et backoff (1 min, 5 min, 30 min).

Après max_attempts, le job passe en dead letter (status dead). Désactiver avec SEND_VIA_JOBS=0 pour revenir à l'envoi synchrone (debug uniquement).

SEND_WORKER_INTERVAL_MS : fréquence de poll (défaut 10 s).
SEND_WORKER_BATCH : nombre de jobs traités par tick.
Warm-up domaine : limite progressive d'envois/jour si warmup_max_per_day configuré sur le domaine.

API & clés d'accès

API REST v1 sous /api/v1 : réservée aux plans Pro et Business. Authentification : JWT (interface web) ou clé API mpx_live_… / mpx_test_… (Bearer ou header X-API-Key).

Scopes : read (GET), write (POST/PATCH/DELETE), send (envois). Créez les clés dans le menu API.

Documentation OpenAPI : GET /api/v1/docs et /api/v1/openapi.json
Guide HTML : GET /api/v1/guide
Rate limit : 120 req/min par clé API.
SDK npm : package mailpilotx (packages/mailpilotx/) : client.send(slug, { to, variables }).
Upsert + send : POST /api/v1/inbound/contacts/upsert-and-send : ajoute un contact à une liste et envoie un mail en une requête.

import { MailPilotX } from 'mailpilotx'

const client = new MailPilotX({
  apiKey: process.env.MPX_KEY,
  baseUrl: 'https://votre-api.com'
})

await client.send('bienvenue', {
  to: 'user@example.com',
  variables: { prenom: 'Alex' }
})

Webhooks sortants

Configurez des URLs pour recevoir des événements en temps réel. Signature HMAC-SHA256 dans le header X-MailPilotX-Signature.

Gestion dans le menu API → section Webhooks. Test ping disponible par endpoint.

transactional.sent : mail transactionnel envoyé
transactional.failed : échec d'envoi transactionnel
campaign.completed : campagne terminée
contact.unsubscribed : désinscription confirmée
send.bounced : bounce enregistré

{
  "id": "uuid-delivery",
  "event": "transactional.sent",
  "created_at": "2026-06-19T12:00:00Z",
  "data": { "send_id": "…", "slug": "bienvenue", "to": "…" }
}

MailPilotX Sync

Sync relie vos outils (HubSpot, Shopify, WooCommerce, Typeform, Zapier…) à une liste MailPilotX via une URL webhook secrète. Pas d’OAuth store : l’outil envoie un POST JSON, le contact est upsert dans la liste.

Réservé aux plans Pro et Business. Menu Sync dans l’app. Option : envoyer un mail transactionnel (slug) à chaque réception.

Création : POST /api/v1/sync (JWT) avec provider, team_id, list_id
Réception : POST /api/v1/sync/hooks/:id/:secret (sans JWT, secret dans l’URL)
JSON minimum : { "email": "…", "name": "…" }. Shopify, Typeform et HubSpot sont parsés nativement
Rate limit : 120 requêtes / minute / connecteur

POST /api/v1/sync/hooks/<id>/<secret>
Content-Type: application/json

{ "email": "contact@entreprise.fr", "name": "Alex Martin" }

Désinscription (RGPD)

Chaque email campagne/transactionnel peut inclure {{unsubscribe_url}}. Le lien mène à une page publique de confirmation one-click.

Les adresses désinscrites sont stockées par équipe (team_unsubscribes) et exclues des prochains envois automatiquement.

Page publique : GET/POST /api/public/unsubscribe/:token
Liste des désinscrits : API segments/unsubscribes ou via votre CRM via webhook contact.unsubscribed.

Listes, contacts & segments

Listes rattachées à une équipe et optionnellement à un projet. Import CSV : colonnes custom → metadata contact.

Segments dynamiques : règles JSON (metadata, liste, ouverture campagne) recalculées à l'envoi. Builder dans le détail d'une liste.

Statuts contact : active, bounced, complained, unsubscribed : exclusion auto à l'envoi.
Automatisations : trigger contact.added_to_list → envoi transactional différé.

Automatisations

Scénarios simples : trigger + délai + action. Interface Automatisations dans le menu.

contact.added_to_list → envoyer mail slug X après N heures
campaign.sent → relance si pas ouvert (J+N, configurable)
Exécution via send_jobs (type automation)

Équipes & rôles

Travaillez en équipe avec rôles owner, admin, editor, viewer. Pro : jusqu’à 3 membres ; Business : jusqu’à 10. Menu Équipes : création, invitation par email, gestion des membres.

Sélecteur d'équipe active (persisté) pour filtrer projets et ressources. Clés API peuvent être limitées à une équipe.

Domaines & délivrabilité

Vous configurez votre domaine expéditeur + SMTP (hôte, port, identifiants chiffrés). Vérification DNS MailPilotX et test SMTP intégrés.

Score délivrabilité : lookup SPF, DKIM, DMARC + état SMTP + bounces. Warm-up optionnel pour monter en volume progressivement.

GET /api/domains/:id/deliverability : score et détail DNS
POST /api/v1/inbound/bounce : remontée bounces depuis votre infra SMTP
Conseil : configurez SPF, DKIM et DMARC sur le domaine expéditeur réel, pas seulement le token MailPilotX.

Médias & URLs signées

Images et vidéos uploadées dans l'éditeur (asset:uuid). À l'envoi, remplacées par des URLs signées publiques temporaires (7 jours par défaut).

Route publique : GET /api/public/assets/:token : pas de JWT requis dans le mail reçu.

Bibliothèque

Modèles d'email complets et sections réutilisables.

Modèles complets → nouveau projet dans l'éditeur. Sections → bloc de modules prêt à personnaliser.

API : GET /api/library?kind=project|section · POST /api/library/:id/import

Abonnement & quotas

Plan gratuit (Starter) avec quota mensuel. Alerte dashboard à 80 % du quota, blocage plan gratuit à 100 %.

Plans payants : au-delà du quota Pro, passer au plan Business. Équipes multi-utilisateurs sur les plans Pro et Business.

Variables d'environnement (API)

Principales variables côté serveur (voir api/.env.example) :

APP_SECRET : chiffrement SMTP (min. 32 caractères)
API_BASE_URL : tracking, désinscription, assets signés
SEND_VIA_JOBS / SEND_WORKER_* : file d'envoi
ASSET_SIGN_SECRET : signature URLs assets (défaut APP_SECRET)
STORAGE_DRIVER=local|s3 : stockage médias (S3 optionnel)
SCHEDULER_* : worker planification campagnes

Ressources & support

API interactive : lien « Guide API » depuis le menu API. Logs structurés (Pino) avec X-Request-Id pour corréler les requêtes.

Health check : GET /api/health et /api/health/db
Audit admin : révocation clés API et actions sensibles journalisées