API d’envoi de courriels
Envoyez côté serveur depuis votre domaine, avec les mêmes quotas, facturation et limites que l’envoi dans la console. Le domaine expéditeur doit correspondre exactement à un domaine d’envoi connecté et actif.
- Authentification : la même clé API utilisateur que pour toutes les autres API ouvertes de la plateforme
- Envoi : POST /api/v1/mail/send ; la réponse est regroupée par destinataire et bounced_addrs est la seule base pour nettoyer votre liste
- Idempotence : avec l’en-tête Idempotency-Key, les soumissions répétées d’une même clé n’envoient qu’une fois, sans doublon de livraison ni de facturation
- Fils de discussion : transmettez in_reply_to et la chaîne references complète pour que les réponses rejoignent la conversation d’origine du destinataire
- Quotas et domaines : interrogez le quota restant du jour et les domaines utilisables pour limiter le débit dans votre système
- Exemples : cURL / Node.js / Python / Go / PHP minimaux et fonctionnels, tous avec idempotence et gestion des rejets définitifs
POST / GET /api/v1/mail/*
Vue d’ensemble
Envoyez depuis vos propres domaines, côté serveur. Les quotas, la facturation et les limites sont exactement les mêmes que dans la console.
Activez l’envoi d’e-mails dans la console et configurez au moins un domaine affiché comme actif. L’envoi depuis un domaine inactif est refusé.
Authentification
Utilise la même clé API de compte que le reste de la plateforme. Créez-la dans Outils et paramètres → Gestion des API.
Console → Outils et paramètres → Gestion des API → Créer une clé. La même clé fonctionne pour les API d’énergie, de cartes virtuelles, d’e-mail et de taux de change ; les points d’accès autorisés dépendent des capacités accordées.
Envoyer un e-mail
POST /api/v1/mail/send
Le domaine de From doit correspondre exactement à un domaine d’envoi configuré et actif.
Limites d’envoi
- to + cc + bcc doivent totaliser au maximum 50 destinataires
- 5 MiB par message, pièces jointes comprises (taille décodée)
- 998 caractères (comptés en caractères, et non en octets — les objets non ASCII ne sont pas pénalisés)
- Jusqu’à 32 pièces jointes ; les pièces jointes intégrées doivent avoir un content_id
- 16 KB au total pour les en-têtes personnalisés, 2048 octets par valeur d’en-tête
Réponse
Les résultats sont regroupés par destinataire, plutôt que résumés par un indicateur global de réussite.
Un envoi à cinq personnes peut avoir 2 livraisons, 1 mise en file et 2 rejets définitifs. bounced_addrs est votre seule source pour nettoyer vos listes — aucun webhook de rejet n’existe. Si vous ignorez ce champ, l’information est perdue : vous continuez à envoyer à des adresses invalides et à payer.
Idempotence
Avec l’en-tête Idempotency-Key, la réutilisation de la même clé ne produit qu’un seul envoi.
Dès qu’un appel peut être relancé automatiquement — délais dépassés, files de tâches, nouvelles tentatives du SDK. Sans cet en-tête, une simple interruption réseau peut provoquer deux livraisons et deux facturations, sans possibilité d’annulation. Utilisez une clé métier, comme un numéro de commande.
Regroupement des conversations
Incluez in_reply_to et references dans vos réponses pour les rattacher à la conversation initiale ; sans eux, chaque réponse crée une nouvelle conversation dans la boîte du destinataire. Envoyez toute la chaîne references — avec seulement in_reply_to, certains clients séparent les conversations de plus de deux messages.
Quota et domaines
Consultez le volume quotidien restant et les domaines d’envoi disponibles pour limiter le débit de votre côté.
Exemples de code
Exemples minimaux fonctionnels pour chaque langage, avec gestion de l’idempotence et des rejets définitifs.
L’envoi d’e-mails est facturé. Les nouvelles clés API exigent par défaut des requêtes signées pour les points d’accès facturés ; tous les exemples suivants utilisent donc la signature version 2 (en-tête X-Sign-Version: 2). La chaîne à signer contient 7 lignes jointes par \n sans saut de ligne final : NEXCORE-HMAC-SHA256-V2, timestamp, nonce, méthode en majuscules, chemin, chaîne de requête et SHA-256 du corps en hexadécimal minuscule. X-Signature est HMAC-SHA256(Secret Key, chaîne à signer) en hexadécimal minuscule. timestamp est en secondes Unix, nonce fait au plus 64 octets ; la chaîne de requête n’a pas de "?" initial et doit être identique à celle envoyée (ligne vide si absente). Le hachage du corps porte sur les octets exacts envoyés. Désactiver l’exigence de signature permet aussi X-API-Key + X-Secret-Key seuls, mais ce n’est pas recommandé.
Questions fréquentes
HTTP 200 signifie-t-il que tous les destinataires ont reçu le courriel ?
Non. Les résultats sont regroupés par destinataire : pour cinq personnes, 2 peuvent être livrées, 1 en attente et 2 rejetées définitivement. Il n’existe pas de webhook de rejet ; bounced_addrs est donc votre seule base de nettoyage. Cessez immédiatement d’envoyer à ces adresses.
Quand faut-il un Idempotency-Key ?
Dès qu’un appel peut être relancé automatiquement : après un délai dépassé, une remise en file de tâche ou une nouvelle tentative du SDK. Sans lui, une coupure réseau peut produire deux courriels et deux facturations, sans annulation possible. Utilisez une clé métier comme l’identifiant de commande.
Pages connexes: Documentation API · API SMTP agrégée · Utiliser l’API d’agrégation SMTP
Chargement…