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 mr_live_xxxxxxxxxxxxxxxx

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 :

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.

curl https://api.mail-reacher.com/v1/emails/send \
  -H "Authorization: Bearer mr_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@exemple.com",
    "from": "noreply@ton-domaine.com",
    "subject": "Bienvenue sur l'\''app",
    "template_id": 42,
    "variables": { "prenom": "Marie" }
  }'

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.

Webhooks

Mail-Reacher reçoit les webhooks bruts de chaque provider et les normalise dans un schéma unique avant de les forwarder à l'URL que tu configures dans ton projet.

Événements

• delivered — l'email a atteint le serveur destinataire
• opened — le destinataire a ouvert l'email (pixel tracker)
• clicked — un lien tracké a été cliqué
• bounced — rejet permanent (hard bounce) ou temporaire (soft)
• complained — le destinataire a marqué comme spam
• unsubscribed — désabonnement via le lien

Payload

{
  "event": "delivered",
  "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 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

SDK Laravel

Le SDK Laravel encapsule l'API REST avec une façade MailReacher, l'intégration native avec la queue, et la configuration via .env.

composer require mail-reacher/laravel

Configuration

MAIL_REACHER_KEY=mr_live_xxxxxxxxxxxxxxxx
MAIL_REACHER_QUEUE=emails

Utilisation

use MailReacher\\Facades\\MailReacher;

MailReacher::send([
    'to' => $user->email,
    'template_id' => config('templates.welcome'),
    'variables' => ['prenom' => $user->name],
])->onQueue('emails');

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.