API REST

Envoyez des e-mails transactionnels via POST /v1/transactional/send. C'est la méthode principale pour envoyer des e-mails via MailLand.

AuthentificationCopier le lien de la section

Incluez votre clé API dans l'en-tête X-API-Key :

X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...

Les identifiants doivent avoir le canal Api activé et être des identifiants de produit Sending.

Envoyer un e-mail uniqueCopier le lien de la section

POST https://api.mail.land/v1/transactional/send

curl -X POST https://api.mail.land/v1/transactional/send \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]"},
    "to": [{"email": "[email protected]"}],
    "subject": "Hello from MailLand",
    "htmlContent": "<p>Your email content here</p>"
  }'

Corps de la requêteCopier le lien de la section

{
  "from": {
    "email": "[email protected]",
    "name": "Your App"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "Jane Doe",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345"
      }
    }
  ],
  "subject": "Your order #{{orderNumber}} has shipped",
  "htmlContent": "<h1>Hi {{firstName}},</h1><p>Your order #{{orderNumber}} is on its way.</p>",
  "textContent": "Hi {{firstName}}, Your order #{{orderNumber}} is on its way.",
  "replyTo": "[email protected]",
  "tags": ["order-shipped", "transactional"],
  "customHeaders": {
    "X-Entity-Ref-ID": "order-12345"
  },
  "tracking": {
    "opens": true,
    "clicks": true
  },
  "priority": "High",
  "idempotencyKey": "order-12345-shipped-v1"
}

Référence des champsCopier le lien de la section

Pièces jointesCopier le lien de la section

Chaque pièce jointe nécessite trois champs :

{
  "attachments": [
    {
      "fileName": "invoice.pdf",
      "contentType": "application/pdf",
      "content": "JVBERi0xLjQKJ...",
      "inline": false
    },
    {
      "fileName": "logo.png",
      "contentType": "image/png",
      "content": "iVBORw0KGgoAAAA...",
      "contentId": "company-logo",
      "inline": true
    }
  ]
}

RéponseCopier le lien de la section

Statut : 202 Accepted

{
  "success": true,
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [],
  "queuedAt": "2026-02-17T10:30:00Z",
  "isSandboxed": false
}

Destinataires rejetésCopier le lien de la section

Les destinataires peuvent être rejetés pour plusieurs raisons :

{
  "success": true,
  "jobId": "...",
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [
    {
      "email": "[email protected]",
      "reason": "Suppressed"
    },
    {
      "email": "[email protected]",
      "reason": "domain_typo",
      "suggestion": "[email protected]"
    }
  ]
}

Raisons de rejet courantes :

• Suppressed : adresse sur la liste de suppression (rebonds/plaintes précédents)
• disposable_domain : fournisseur d'e-mail jetable détecté
• domain_typo : faute de frappe probable dans le domaine (inclut le champ suggestion)

Vérification préalableCopier le lien de la section

Vérifiez votre capacité d'envoi avant de faire la requête réelle :

GET https://api.mail.land/v1/transactional/send/check?recipientCount=1

curl https://api.mail.land/v1/transactional/send/check?recipientCount=1 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

{
  "canSend": true,
  "rateLimitStatus": {
    "currentSecond": 2,
    "limitPerSecond": 50,
    "currentHour": 450,
    "limitPerHour": 5000,
    "currentDay": 8200,
    "limitPerDay": 50000
  },
  "monthlyUsed": 125000,
  "monthlyLimit": 500000
}

Si canSend est false, le champ reason explique pourquoi (limite de débit, quota, statut du compte, etc.).

IdempotenceCopier le lien de la section

Réessayer un envoi après une expiration réseau ne doit pas livrer l'e-mail deux fois. Avec une clé d'idempotence, une nouvelle tentative rejoue la réponse d'origine au lieu de renvoyer.

Envoyez la clé en en-tête (recommandé) :

X-Idempotency-Key: order-12345-shipped-v1

Ou utilisez le champ idempotencyKey du corps. Les deux sont acceptés, et vous pouvez envoyer les deux uniquement si les valeurs sont identiques.

RèglesCopier le lien de la section

• Portée. X-Idempotency-Key n'est accepté que sur POST /v1/transactional/send et POST /v1/transactional/send-batch. Aucun autre endpoint ne le lit.
• Format. 1 à 255 caractères : lettres, chiffres, _ et -. Les clés sont comparées exactement, sans rognage ni normalisation de casse.
• Fenêtre. Une clé reste rejouable pendant 24 heures. Ensuite, la même clé est traitée comme une nouvelle requête.
• Rejeu. Une nouvelle tentative dans la fenêtre renvoie la réponse d'origine telle quelle (mêmes identifiants, même statut) et n'envoie rien.
• Unicité. Les clés sont uniques par compte. Réutiliser une clé pour un autre endpoint est rejeté avec 409 ; utilisez une clé distincte par opération.

ID de corrélationCopier le lien de la section

Suivez les requêtes entre les systèmes en incluant un ID de corrélation :

X-Correlation-ID: my-app-order-12345

ou

X-Request-ID: my-app-order-12345

L'ID de corrélation apparaît dans les journaux et le flux d'activité.

En-têtes de limite de débitCopier le lien de la section

Les réponses réussies incluent des informations de limite de débit par IP :

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295

En cas de limitation de débit (429) par le moteur de politique d'envoi, un en-tête Retry-After indique le nombre de secondes à attendre :

Retry-After: 30

Une requête transactionnelle peut nommer jusqu'à 5 destinataires, et chacun compte dans vos limites de taux. Si c'est plus que votre limite par seconde (par exemple 1 par seconde avec un forfait de 60 par minute), la requête est acceptée lorsqu'aucune autre requête n'a été acceptée dans la même seconde ; sinon elle reçoit 429 avec Retry-After: 1 et réussit si elle est relancée la seconde suivante, dans la limite par minute. Voir Limites de taux.

Un 429 au niveau IP inclut aussi X-RateLimit-Reset sous forme d'heure UTC ISO-8601.

Réponses d'erreurCopier le lien de la section

Toutes les erreurs renvoient un corps JSON :

{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "timestamp": "2026-02-17T10:30:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Codes d'erreurCopier le lien de la section

Limite de destinataires transactionnelsCopier le lien de la section

Les identifiants transactionnels imposent un maximum de 5 destinataires par requête d'envoi. Cela empêche l'utilisation abusive des flux transactionnels pour l'envoi en masse. Si vous avez besoin de plus de destinataires, utilisez un identifiant Marketing avec l'envoi par lots.

Utilisation des modèlesCopier le lien de la section

Au lieu du HTML en ligne, référencez un modèle enregistré :

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "resetLink": "https://app.example.com/reset?token=abc123"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr",
  "variables": {
    "companyName": "Acme Inc"
  }
}

Le subject provient du modèle. En cas de clé identique, la valeur propre du destinataire dans to[].variables remplace les variables globales : la même règle que pour le contenu en ligne. Consultez Modèles pour créer et gérer des modèles.

Étapes suivantesCopier le lien de la section

• Envoi par lots : envoyer à plusieurs destinataires en une seule fois
• Relais SMTP : envoyer via SMTP plutôt que REST
• Modèles : créer des modèles d'e-mail réutilisables
• E-mails planifiés : planifier des e-mails pour une livraison future