Configurer la Mail API

La Mail API vous permet d'envoyer des messages par e-mail : vous envoyez un e-mail à l'adresse fixe de votre configuration, seven l'analyse à l'aide de vos motifs et envoie le résultat sous forme de SMS, de message RCS, WhatsApp ou Voice. Vous définissez une fois pour toutes dans la configuration où figurent le destinataire, le texte et l'expéditeur dans l'e-mail. La Mail API s'adapte ainsi à votre application, par exemple à un outil de monitoring, à une boutique en ligne ou à votre logiciel de messagerie.

Pour savoir comment envoyer ensuite des messages, consultez les articles Envoyer des SMS par e-mail et Envoyer des RCS par e-mail.

Créer une configuration Mail API

Ouvrez Développeur -> Accès API. La liste affiche toutes les clés REST API, les configurations Mail API et les connexions SMPP. Cliquez en haut à droite sur Créer et sélectionnez Mail API.

Liste des accès API avec une configuration Mail API et le bouton Créer (vue du dashboard en anglais)

La boîte de dialogue Créer une adresse Mail API vous guide à travers la configuration en cinq étapes. Vous pouvez créer autant de configurations que vous le souhaitez, chacune avec ses propres expéditeurs, sa propre adresse fixe et ses propres motifs.

Étape 1 : Accès

Sous Expéditeurs autorisés, saisissez les adresses e-mail depuis lesquelles vous envoyez : une adresse par ligne, jusqu'à dix par configuration. La passerelle n'accepte pas les e-mails provenant d'autres adresses. Avec *@votre-domaine.fr, vous autorisez toutes les adresses d'un domaine.

Étape Accès avec deux expéditeurs autorisés (vue du dashboard en anglais)

Ne sont pas autorisés :

les adresses sur les domaines propres à seven (seven.io, sms77.io, sms77.de et leurs sous-domaines)
les autorisations de domaine (*@domaine) pour les fournisseurs de messagerie gratuits comme Gmail ou GMX
les adresses déjà prouvées dans un autre compte seven

Ces vérifications ont lieu dès que vous cliquez sur Suivant, afin que vous voyiez les erreurs directement dans le champ de saisie.

Étape 2 : Motifs

Ici, vous décrivez à quoi ressemblent vos e-mails. Le texte littéral du motif doit figurer tel quel dans l'e-mail et sert d'ancre, les variables entre doubles accolades capturent le texte qui se trouve entre les deux.

Étape Motifs avec le motif {{to}} pour le préfixe d'adresse et {{text}} pour le corps (vue du dashboard en anglais)

Motif du préfixe d'adresse (par défaut : vide) : s'applique à la partie de l'adresse située avant le token. Avec {{to}}, un e-mail envoyé à 4917612345678.TOKEN@gateway.seven.io part exactement vers ce numéro. Si le champ reste vide, envoyez vos e-mails à l'adresse sans préfixe : le destinataire provient alors des paramètres (étape 3).
Motif de l'objet (par défaut : vide) : vide signifie que l'objet est ignoré.
Motif du corps (par défaut : {{text}}) : avec la valeur par défaut, l'ensemble du texte de l'e-mail devient le texte du message.

Les variables les plus importantes sont {{to}} (destinataire : numéro de téléphone, contact ou groupe), {{text}} (texte du message) et {{from}} (identifiant d'expéditeur). Sous Avancé et WhatsApp, vous trouverez d'autres variables, par exemple {{delay}} pour l'envoi différé ou {{label}}. La liste complète figure dans la documentation Mail API.

Exemple : le motif du corps (({{text}})) delay={{delay}} correspond à l'e-mail ((Votre commande est en route.)) delay=2027-01-15 08:00:00 et planifie le message pour le 15/01/2027 à 8 h.

Étape 3 : Paramètres

Sous Valeurs par défaut, vous définissez ce qui s'applique lorsque les motifs ne fournissent rien :

Destinataire fixe : s'applique lorsque aucun motif ne capture {{to}} et est alors obligatoire.
Expéditeur du message : s'applique lorsque aucun motif ne capture {{from}}. Vide signifie l'expéditeur par défaut de votre compte.
Type : SMS, RCS, WhatsApp ou Voice.

Sous Options, vous pouvez indiquer un Mail d'erreur auquel les messages d'erreur doivent être envoyés.

Étape Paramètres avec Destinataire fixe, Expéditeur du message, Type et Mail d'erreur (vue du dashboard en anglais)

Étape 4 : Aperçu

Avant de pouvoir enregistrer, vous testez vos motifs sur un véritable e-mail. Chaque configuration dispose pour cela d'une Adresse de test avec le suffixe -test, soit TOKEN-test@gateway.seven.io (avec préfixe, par exemple 4917612345678.TOKEN-test@gateway.seven.io). Via Ouvrir l'e-mail d'exemple, votre logiciel de messagerie prépare un e-mail adapté.

Envoyez l'e-mail de test depuis l'un des expéditeurs autorisés. Dès qu'il arrive, vous voyez les variables capturées et le message qui en résulterait. Les e-mails envoyés à l'adresse de test ne déclenchent aucun envoi.

Étape Aperçu avec un e-mail de test reçu, les variables capturées et le résultat (vue du dashboard en anglais)

Important :

Sans e-mail de test, la configuration ne peut pas être enregistrée, y compris lors d'une modification ultérieure.
Un e-mail de test provenant d'une adresse qui ne figure pas dans la liste des expéditeurs autorisés est affiché, mais ne compte pas. Dans ce cas, envoyez-le depuis le bon compte.
Si plusieurs e-mails de test arrivent, le plus récent qui correspond sert d'aperçu. Les plus anciens peuvent être dépliés.
Si votre réseau bloque la connexion en direct du dashboard, la boîte de dialogue récupère automatiquement les e-mails de test reçus toutes les quelques secondes. Avec Récupérer l'e-mail de test, vous déclenchez cette récupération immédiatement.

Étape 5 : Sécurité

La dernière étape affiche l'Adresse fixe de la configuration (TOKEN@gateway.seven.io), la Preuve de l'expéditeur pour chaque expéditeur autorisé et le statut de la Vérification DMARC. Cliquez sur Enregistrer pour terminer la configuration, qui est immédiatement utilisable.

Étape Sécurité avec l'adresse fixe, un expéditeur prouvé et un domaine avec un enregistrement TXT en attente (vue du dashboard en anglais)

Prouver les expéditeurs et vérification DMARC

La passerelle n'accepte en principe que les e-mails des expéditeurs autorisés. Vous pouvez en outre prouver que ces expéditeurs vous appartiennent réellement. Dès que tous les expéditeurs d'une configuration sont prouvés, la Vérification DMARC s'active automatiquement. Il n'existe pas d'interrupteur pour cela.

Voici comment prouver vos expéditeurs :

Adresse individuelle : envoyez depuis cette adresse à l'adresse de test un e-mail de test qui passe la vérification DMARC. L'e-mail de test de l'étape 4 compte déjà comme preuve s'il passe DMARC.
Autorisation de domaine (*@domaine) : créez sur le domaine un enregistrement TXT seven-mail-api-verify=TOKEN et cliquez sur Vérifier le DNS. Le domaine (ou un domaine parent) doit également disposer d'un enregistrement DMARC. seven vérifie les deux quotidiennement et retire la preuve si l'enregistrement TXT est absent pendant quelques jours.

Lorsque la vérification DMARC est active, la passerelle n'accepte plus que les e-mails dont le domaine expéditeur passe la vérification DMARC. La condition est un enregistrement DMARC de votre domaine associé à SPF ou DKIM. Les transferts ne posent pas de problème tant que la signature DKIM est conservée. Les e-mails refusés apparaissent avec le code 904 dans le Débogueur. Le message d'erreur est alors envoyé exclusivement à l'adresse du mail d'erreur, jamais à l'expéditeur, car celui-ci pourrait être usurpé.

Si un e-mail de test ne passe pas la vérification, la boîte de dialogue en indique la raison, par exemple que le domaine expéditeur n'a pas d'enregistrement DMARC, que ni SPF ni DKIM ne correspondent au domaine expéditeur ou que le résultat concerne un autre domaine que l'adresse From.

Bon à savoir : vous ne pouvez plus ajouter d'expéditeurs non prouvés à une configuration dont la vérification DMARC est active. Pour les expéditeurs sans DMARC, créez une seconde configuration.

Adresse sans token

Lorsque la vérification DMARC est active, vous pouvez en outre activer l'option Autoriser en plus l'adresse sans token à l'étape Sécurité. Le préfixe suffit alors comme adresse complète, par exemple 4917612345678@gateway.seven.io. seven attribue l'e-mail uniquement d'après l'expéditeur prouvé de votre configuration. L'adresse avec token continue de fonctionner. Si vous souhaitez combiner token et vérification DMARC, laissez cette option désactivée.

Étape Sécurité avec la vérification DMARC active et l'option Adresse sans token activée (vue du dashboard en anglais)

Si le même expéditeur prouvé utilise plusieurs configurations avec cette option, l'e-mail n'est pas attribué et n'est pas envoyé.

Autres paramètres de la Mail API

Ouvrez Développeur -> Paramètres et dépliez la section Mail API. Ces paramètres s'appliquent à toutes les configurations Mail API.

Section Mail API dans les paramètres développeur (vue du dashboard en anglais)

Nombre maximum de caractères : limite la longueur du message afin que des signatures ou pieds de page envoyés par erreur ne fassent pas grimper les coûts. 0 désactive la limite.
Supprimer la signature : filtre le texte cité (> comme ces lignes) avant l'envoi.
Notification en cas d'erreur / Push HTTP en cas d'erreur : vous êtes informé par e-mail ou par push HTTP lorsqu'un e-mail ne peut pas être traité, par exemple parce qu'un motif ne correspond pas ou que le destinataire manque.
Insérer l'expéditeur dans le SMS : ajoute l'adresse de l'expéditeur de l'e-mail au début du message, au choix sous forme d'Adresse complète (unutilisateur@domaine.fr), de Partie locale (avant @) (unutilisateur) ou pas du tout (Ne pas ajouter).

Configurations existantes (Legacy)

Les configurations créées avant l'introduction de l'adresse fixe sont signalées par Legacy dans la liste. Elles continuent de fonctionner dans le format classique : le numéro de téléphone figure devant @gateway.seven.io, les paramètres de contrôle comme key=, from= ou type= figurent dans l'objet. Les configurations Legacy fonctionnent sans changement et sans limite de durée, mais n'autorisent qu'un seul expéditeur et aucune vérification DMARC. Pour les nouvelles applications, nous recommandons une configuration avec adresse fixe et motifs.

Documentation

Vous trouverez la référence complète avec toutes les variables, des exemples et le format classique dans la documentation Mail API.