Documentation Mail-Reacher

Démarrage rapide

En 5 minutes, tu peux envoyer ton premier email transactionnel via Mail-Reacher. Le parcours est volontairement court parce que la valeur est dans le routing multi-provider, pas dans la configuration.

1. Crée un compte gratuit puis un projet depuis le dashboard.
2. Branche un provider (AWS SES, Postmark, Mailgun, SendGrid ou un SMTP custom).
3. Crée un environnement test et un environnement production.
4. Génère une clé API pour l'environnement test (préfixe mr_test_).
5. Crée un premier template MJML depuis l'éditeur visuel.
6. Appelle POST /v1/emails/send avec ta clé.

En environnement test, l'email est simulé et visible dans une inbox interne. En production, il part via ton provider configuré. Le code est strictement identique — seule la clé change.

Concepts

Mail-Reacher s'organise autour de quatre objets que tu retrouves partout dans le dashboard et dans l'API.

Authentification

L'API utilise le schéma Bearer token. Passe ta clé dans le header Authorization de chaque requête.

Authorization: Bearer demo-token

Préfixes de clés

• mr_test_… — environnement de test, l'envoi est simulé.
• mr_live_… — environnement de production, envoi réel.

Scopes

Chaque clé porte des scopes qui limitent les actions autorisées :

Les clés restent isolées par projet : un ID de contact ou de template appartenant à un autre projet renvoie un 404. Une clé avec seulement contacts:read ne peut pas créer, modifier ou supprimer de contact.

Envoyer un email

L'endpoint POST /v1/emails/send accepte un payload JSON et retourne un message_id que tu peux corréler avec les webhooks.

Pour un environnement configuré en analyse marketing, ajoute "tracking_consent": true uniquement après avoir recueilli le consentement du destinataire. La valeur est enregistrée dans les métadonnées de l'envoi ; elle n'apparaît pas dans l'email. Si elle est absente ou fausse, le tracking Mail-Reacher et celui du provider sont désactivés ; l'envoi est bloqué si cette désactivation ne peut pas être garantie. Le mode « délivrabilité transactionnelle » est réservé aux messages liés à un service demandé : sans consentement explicite, il autorise uniquement le signal d'ouverture Mail-Reacher, pas les clics ni le tracking provider. Le tracking est aussi désactivé pour les messages envoyés à plusieurs destinataires.

curl https://mail-reacher.com/api/emails/send \
  -H "Authorization: Bearer mr_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{ "email": "user@exemple.com", "name": "Marie" }],
    "from_email": "noreply@ton-domaine.com",
    "from_name": "Ton App",
    "reply_to": "support@ton-domaine.com",
    "subject": "Bienvenue sur l'\''app",
    "html": "<p>Bonjour Marie</p>",
    "text": "Bonjour Marie",
    "metadata": { "source": "site" }
  }'

Paramètres

Réponse

{
  "message_id": "msg_01HX9Z7K3RVZ8N4P5Q6T2W8X9Y",
  "status": "queued",
  "environment": "production",
  "provider": "aws-ses"
}

Templates MJML

Les templates Mail-Reacher utilisent MJML — un langage qui compile vers du HTML responsive compatible avec les 30+ clients email majeurs (Outlook, Gmail, Apple Mail, Yahoo, Thunderbird…).

Variables dynamiques

Tu peux injecter des variables avec la syntaxe Handlebars classique. Les variables non définies au moment de l'envoi déclenchent une erreur de validation côté API.

<mj-text>
  Bonjour {{ prenom }},
  ton compte est prêt à <a href="{{ lien_activation }}">activer</a>.
</mj-text>

État actif

Un template peut être marqué actif ou inactif. Seuls les templates actifs peuvent être utilisés à l'envoi. L'historique de versions et le rollback sont sur la roadmap publique.

Tracking & événements

Mail-Reacher utilise son propre tracker : un pixel d'ouverture et la réécriture des liens cliquables sont injectés dans les emails au moment de l'envoi. Les événements résultants sont accessibles depuis l'API et le dashboard, indépendamment du provider derrière l'envoi.

Événements

• queued — l'envoi est accepté par Mail-Reacher
• sent — l'email a été remis au provider
• opened — pixel d'ouverture chargé par le destinataire
• clicked — un lien tracké a été cliqué
• failed — erreur côté provider à l'envoi

Payload (forward webhook)

Quand un webhook de forward est configuré sur ton projet, chaque événement est envoyé en POST sur l'URL fournie avec le payload suivant :

{
  "event": "opened",
  "message_id": "msg_01HX9Z...",
  "provider": "aws-ses",
  "to": "user@exemple.com",
  "from": "noreply@ton-domaine.com",
  "occurred_at": "2026-05-02T10:14:32Z",
  "metadata": {
    "campaign": "onboarding",
    "user_id": 1234
  }
}

Signature

Chaque requête de forward contient un header X-MailReacher-Signature avec un HMAC-SHA256 du body, signé avec le secret de ton projet. Vérifie-le systématiquement côté app pour rejeter les requêtes non authentiques.

Mail-Check

Le Mail-Check audite la délivrabilité de tes envois en lançant 10 vérifications consolidées en un score normalisé sur 10. Tu peux le déclencher manuellement, programmer des runs récurrents, ou l'automatiser à chaque modification de provider.

• SPF — présence et validité du record TXT
• DKIM — vérification de la signature DomainKeys
• DMARC — policy et alignement
• Reverse DNS — l'IP source pointe vers le bon nom
• Blacklists — scan de 20+ listes (Spamhaus, SORBS, Barracuda, UCEProtect…)
• Headers — From, Reply-To, List-Unsubscribe, Date, Message-ID
• Contenu — détection de patterns spam classiques
• TLS — version, chiffrement, validité du certificat
• MX — record et résolution
• IPs — IP source, réputation, géolocalisation

Providers supportés

SDKs & packages

Utilise les packages officiels quand tu veux des helpers typés plutôt qu'un appel REST brut. La clé MAILREACHER_API_KEY reste côté serveur et sélectionne l'environnement, donc le provider configuré ou le mode simulation.

yarn add @mail-reacher/sdk
yarn add @mail-reacher/next
yarn add @mail-reacher/nodemailer
yarn add @mail-reacher/tanstack-start

composer require codiblenet/mail-reacher-php
composer require codiblenet/laravel-mail-reacher

Configuration Laravel

MAIL_MAILER=mailreacher
MAILREACHER_API_KEY=demo-token

L'endpoint reste fixe sur mail-reacher.com : pas de variable MAILREACHER_BASE_URL à configurer.

Codes d'erreur

L'API utilise les codes HTTP standards. Le body contient toujours un objet d'erreur avec un code machine-friendly et un message humain.

Rate limits

Les limites sont définies par environnement (pas par clé), ce qui permet d'avoir plusieurs clés sur un même environnement sans se marcher dessus.

• Free tier : 60 envois / minute, 1 000 / mois
• Pro : 600 envois / minute, 100 000 / mois
• Business : limites custom

Les headers X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset sont retournés sur chaque réponse.