Clés API

Les clés API (identifiants) authentifient votre application auprès de l'API MailLand. Chaque clé est délimitée par produit, mode, flux, canal, et peut être optionnellement restreinte par domaine et adresse IP.

Dans le tableau de bord, créez et gérez les clés sous Credentials dans la barre latérale (section Global). Les mêmes opérations sont disponibles via l'API /v1/credentials décrite ci-dessous.

Les exemples Authorization: Bearer de cette page utilisent le jeton d'accès JWT renvoyé par POST /v1/auth/login (voir Login). Les clés API sont différentes : envoyez-les dans l'en-tête X-API-Key, jamais comme jeton Bearer.

Format des clésCopier le lien de la section

Toutes les clés API MailLand suivent ce format :

ml_{mode}{product}{stream?}_{random45chars}

• ml_ : préfixe pour toutes les clés
• Mode : p (Production) ou s (Sandbox)
• Produit : e (Sending), i (Inbound), v (Validation)
• Flux (Sending uniquement) : t (Transactional) ou m (Marketing)
• 45 caractères aléatoires

Exemples :

ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...  → Production Sending Transactional
ml_sem_Xn7Kp2qR4tW9yB1cD6eF...  → Sandbox Sending Marketing
ml_pi_Mn5Jp8kL3rV6wA2xC4fG...   → Production Inbound
ml_pv_Qw9Er3tY6uI1oP5aS8dF...   → Production Validation

Propriétés des identifiantsCopier le lien de la section

Lors de la création d'un identifiant, vous configurez les éléments suivants :

channels est une seule chaîne, jamais un tableau. Envoyez "channels": "Api, Smtp" pour autoriser les deux canaux ; ["Api", "Smtp"] est rejeté avec 400.

Créer un identifiantCopier le lien de la section

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Transactional",
    "product": "Sending",
    "mode": "Production",
    "stream": "Transactional",
    "channels": "Api",
    "scope": "AllDomains",
    "rateLimitPerHour": 5000,
    "rateLimitPerDay": 50000
  }'

{
  "id": "n4k9pq2rt8mwxa",
  "name": "Production Transactional",
  "key": "ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...",
  "keyPrefix": "ml_pet_Ab3Kx9mN",
  "product": "sending",
  "mode": "production",
  "stream": "transactional",
  "channels": "api",
  "scope": "allDomains",
  "sandboxBehavior": "logOnly",
  "rateLimitPerHour": 5000,
  "rateLimitPerDay": 50000,
  "isActive": true,
  "createdAt": "2026-02-17T10:00:00Z"
}

Portée : Restrictions de domaineCopier le lien de la section

Par défaut, les identifiants peuvent envoyer depuis n'importe quel domaine vérifié dans votre espace de travail (AllDomains). Pour restreindre un identifiant à des domaines spécifiques :

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing - notifications.com only",
    "product": "Sending",
    "mode": "Production",
    "stream": "Marketing",
    "channels": "Api",
    "scope": "SelectedDomains",
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

Vous pouvez également mettre à jour les attributions de domaines après la création :

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

Restrictions IPCopier le lien de la section

Restreignez un identifiant à des adresses IP ou des plages CIDR spécifiques :

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/allowed-ips \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIps": [
      { "ipAddress": "203.0.113.10", "description": "Production server" },
      { "ipAddress": "198.51.100.0/24", "description": "Office network" }
    ]
  }'

Lorsque des restrictions IP sont configurées, les requêtes API provenant d'adresses IP non répertoriées retournent 403 IP_NOT_ALLOWED.

Configuration des canauxCopier le lien de la section

Le champ channels contrôle où un identifiant peut s'authentifier :

Pour utiliser un identifiant avec le relay SMTP, assurez-vous que Smtp est inclus dans les canaux. Lors de l'authentification via SMTP, utilisez n'importe quel nom d'utilisateur et la clé API comme mot de passe.

Rotation des clésCopier le lien de la section

Faites tourner la clé API d'un identifiant sans interruption de service grâce à une période de grâce :

curl -X POST https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/rotate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriodHours": 24
  }'

{
  "key": "ml_pet_Yn8Lq3rS5uW0zA4bC7dE...",
  "oldKeyExpiresAt": "2026-02-18T10:00:00Z"
}

Pendant la période de grâce (24 heures par défaut), l'ancienne et la nouvelle clé sont toutes deux valides. Après la période de grâce, l'ancienne clé cesse de fonctionner.

Mode SandboxCopier le lien de la section

« Sandbox » recouvre deux choses distinctes qui se combinent :

1. Identifiants Sandbox (mode: Sandbox). Pour le développement, la CI/CD et le staging. Le sort d'un envoi dépend du sandboxBehavior de l'identifiant :

• LogOnly (par défaut) : la requête est validée et reçoit 202, mais rien n'est livré et aucun message n'est créé. La réponse contient isSandboxed: true, sandboxReason: "credential_sandbox_mode" et un messageIds vide.
• AllowListOnly : les destinataires correspondant à la liste d'autorisation sandbox de votre espace de travail reçoivent réellement l'e-mail ; les autres figurent dans rejectedRecipients avec le motif recipient_not_in_sandbox_allowlist. Si aucun destinataire n'est autorisé, la réponse reste 202 avec acceptedRecipients: [] et sandboxReason: "all_recipients_not_in_sandbox_allowlist".

Par SMTP, un identifiant sandbox ne livre jamais : le message est accepté et enregistré mais pas envoyé, quel que soit son sandboxBehavior.

2. Espaces de travail Sandbox. Un nouvel espace de travail démarre au niveau de vérification Sandbox (voir Espaces de travail). Tant qu'il n'est pas vérifié, l'envoi est limité aux destinataires de la liste d'autorisation, même avec un identifiant Production. Tout autre destinataire est refusé avec 429 SENDING_BLOCKED (« Recipient '…' is not in sandbox allowlist. Add to allowlist or complete verification. »).

Gérez la liste d'autorisation dans le tableau de bord sous Paramètres → Sandbox Allow List. Une entrée est une adresse ([email protected]) ou un domaine entier (*@example.com). La même liste est disponible via GET /v1/account/settings/sandbox-allowlist, POST /v1/account/settings/sandbox-allowlist, DELETE /v1/account/settings/sandbox-allowlist/{email} (jeton bearer du tableau de bord ; POST accepte email et description facultative).

Gérer les identifiantsCopier le lien de la section

Lister les identifiantsCopier le lien de la section

curl "https://api.mail.land/v1/credentials?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Filtrer par produit ou mode :

curl "https://api.mail.land/v1/credentials?product=Sending&mode=Production" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Mettre à jour un identifiantCopier le lien de la section

curl -X PATCH https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "rateLimitPerHour": 10000,
    "isActive": false
  }'

Tous les champs sont facultatifs : n'incluez que ce que vous souhaitez modifier.

Supprimer un identifiantCopier le lien de la section

curl -X DELETE https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Retourne 204 No Content en cas de succès. Les identifiants supprimés cessent immédiatement de s'authentifier. La suppression révoque la clé : l'identifiant reste listé dans GET /v1/credentials avec isActive: false.

Limites de débitCopier le lien de la section

Chaque identifiant dispose de ses propres limites de débit, indépendantes des autres identifiants :

Lorsqu'une limite de débit est dépassée, l'API retourne 429 avec les en-têtes X-RateLimit-* :

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708171800
Retry-After: 45

Étapes suivantesCopier le lien de la section

• Démarrage rapide : envoyez votre premier e-mail
• REST API : référence complète de l'API d'envoi
• SMTP Relay : authentifiez-vous avec votre clé API via SMTP