API d’e-mail transactionnel
Un appel REST pour chaque e-mail envoyé par votre produit
Envoyez reçus, réinitialisations de mot de passe, alertes et avis de compte via POST /v1/transactional/send. MailLand vérifie la requête, signe chaque message avec la clé DKIM de votre domaine, le remet à ses serveurs de messagerie et vous indique ce qu’il est devenu. Les serveurs sont hébergés chez Hetzner en Allemagne.
curl -X POST https://api.mail.land/v1/transactional/send \
-H "X-API-Key: ml_pet_..." \
-H "X-Idempotency-Key: order-1042-receipt" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "[email protected]", "name": "Your App" },
"to": [{ "email": "[email protected]", "name": "Jane" }],
"subject": "Your receipt for order 1042",
"htmlContent": "<p>Thanks, Jane. Your payment was received.</p>",
"textContent": "Thanks, Jane. Your payment was received.",
"tags": ["receipt"]
}'Ce qui se passe après votre appel à l’API
Quatre étapes, chacune visible pour vous dans la réponse, le journal des messages ou un webhook.
Vérifié
L’API vérifie le domaine d’envoi, la portée et les limites de votre clé, ainsi que chaque destinataire. Les adresses de la liste de suppression sont refusées et listées dans rejectedRecipients ; si la protection contre les fautes de frappe et les domaines jetables est activée, ces adresses y figurent aussi, avec une correction suggérée en cas de faute de frappe.
En file d’attente
Chaque message accepté est enregistré dans la base de données de MailLand avant que l’API ne réponde 202 Accepted, puis transmis à la file de livraison. La réponse contient l’identifiant de la tâche, un identifiant de message par destinataire et l’heure de mise en file ; un envoi planifié renvoie à la place un identifiant de planification.
Signé et envoyé
Chaque destinataire reçoit une copie distincte avec son propre identifiant de message et sans Cc visible, signée avec la clé DKIM de votre domaine et envoyée depuis les adresses IP d’envoi partagées de MailLand.
Signalé
Les événements délivré, différé, rebond, échec et plainte parviennent à votre webhook et au journal des messages. Chaque événement porte une version de statut, ce qui vous permet de les appliquer dans le bon ordre.
Ce que l’API vous apporte
Chacun de ces éléments est un champ, un en-tête ou un endpoint, documenté avec des exemples.
Modèles enregistrés avec variables
Conservez vos modèles HTML et texte dans MailLand et remplissez les {{placeholders}} pour chaque destinataire. Si une variable n’a pas de valeur, le message n’est pas envoyé avec l’espace réservé brut : l’API répond 422 et indique ce qui manque.
Clés d’idempotence
Joignez un en-tête X-Idempotency-Key à un envoi. Une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse d’origine et n’envoie rien : une nouvelle tentative après un délai d’attente réseau dépassé n’envoie donc pas de deuxième copie.
Envois planifiés
Ajoutez scheduledAt pour planifier un envoi jusqu’à 7 jours à l’avance. Listez, replanifiez ou annulez un message planifié via l’API tant qu’il n’est pas parti.
Pièces jointes et images intégrées
Joignez jusqu’à 10 fichiers et 10 MiB par message, y compris des images intégrées que votre HTML référence par Content-ID.
Tags et en-têtes personnalisés
Ajoutez des tags aux messages pour les filtrer dans les statistiques, les journaux et les webhooks, ajoutez vos propres en-têtes et définissez une adresse de réponse par message.
Vérification préalable
GET /v1/transactional/send/check vous indique si votre compte peut envoyer en ce moment, avec l’utilisation actuelle de la limite de débit et le quota mensuel. Il ne vérifie pas un expéditeur ou un destinataire précis.
Clés sandbox
Une clé sandbox accepte et enregistre les requêtes sans les livrer, ou ne livre qu’aux adresses d’une liste d’autorisation que vous contrôlez : vos e-mails de test n’atteignent que les adresses que vous choisissez.
Des clés à portée limitée
Limitez chaque clé à un flux, à des domaines d’envoi choisis, à une liste d’IP autorisées, à des limites par minute, par heure et par jour et à une date d’expiration. Renouvelez-la depuis le panneau ou via l’API.
Sachez ce qu’est devenu chaque message
Accepter une requête n’est que la moitié du travail. MailLand vous dit ce qui s’est passé ensuite.
Webhooks signés
Abonnez-vous aux événements délivré, différé, rebond, échec et plainte. Chaque requête est signée en HMAC-SHA256 dans l’en-tête X-MLND-Signature et renvoyée lorsque votre endpoint échoue.
Journal des messages
Retrouvez n’importe quel message par son identifiant et consultez chaque événement de son historique. Les journaux sont conservés 30, 90 ou 180 jours selon votre plan.
Suppression automatique
Les rebonds définitifs et les plaintes sont ajoutés automatiquement à votre liste de suppression, et les envois ultérieurs à ces adresses sont refusés avant de partir.
Une v1 qui ne fait que s’enrichir
La version 1 de l’API évolue uniquement par ajouts : de nouveaux champs et événements peuvent apparaître, mais rien n’est supprimé et rien ne change de sens. Une modification incompatible est publiée en /v2, annoncée au moins 180 jours à l’avance, et /v1 continue de fonctionner en parallèle pendant 180 jours.
Du HTTPS simple, dans tous les langages
MailLand ne propose pas encore de SDK. L’API, c’est du JSON sur HTTPS avec un en-tête X-API-Key, et la documentation, disponible en sept langues, présente chaque requête en curl, JavaScript, Node.js, Python, PHP, C#, Java et Go.
Hébergé dans l’UE
Les serveurs de MailLand sont hébergés chez Hetzner en Allemagne, principalement à Nuremberg, et une copie de sauvegarde chiffrée est conservée à Varsovie, en Pologne. Quelques sous-traitants ultérieurs, comme Cloudflare et Stripe, peuvent traiter des données limitées hors de l’UE dans le cadre des clauses contractuelles types de l’UE. Le DPA les liste tous.
Lire le DPAQuestions sur l’API d’e-mail transactionnel
Existe-t-il un plan gratuit ?
Oui. Le plan Free comprend 1 000 e-mails par mois sans frais, avec la même API REST et le même relais SMTP que les plans payants. Aucune carte bancaire n’est nécessaire pour commencer.
Proposez-vous des SDK ?
Pas encore. L’API, c’est du JSON sur HTTPS : n’importe quel client HTTP fonctionne. La documentation contient des exemples prêts à copier en curl, JavaScript, Node.js, Python, PHP, C#, Java et Go.
Comment éviter qu’une nouvelle tentative envoie l’e-mail deux fois ?
Joignez un en-tête X-Idempotency-Key (ou le champ idempotencyKey) à POST /v1/transactional/send ou send-batch. Une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse d’origine et n’envoie rien. Ces deux endpoints sont les seuls à accepter une clé.
Une requête peut-elle viser de nombreux destinataires ?
Une requête transactionnelle accepte jusqu’à 5 destinataires, et chacun reçoit une copie distincte. Pour les envois en masse, utilisez une clé marketing avec POST /v1/transactional/send-batch, qui accepte jusqu’à 10 000 destinataires par requête.
Que se passe-t-il lorsqu’un message rebondit ?
Un rebond définitif ou une plainte ajoute l’adresse à votre liste de suppression et est envoyé à votre webhook sous forme d’événement. Les envois ultérieurs à cette adresse sont refusés et listés dans rejectedRecipients.
Quelles sont les limites d’envoi ?
Chaque plan fixe un volume mensuel et un débit d’envoi par minute, indiqués sur la page des tarifs. Une clé peut avoir ses propres limites, plus basses. Au-delà d’une limite, l’API répond 429 avec un en-tête Retry-After.
Envoyez votre premier e-mail dès aujourd’hui
Créez un compte gratuit, vérifiez votre domaine et appelez l’API. 1 000 e-mails par mois sont gratuits.