Mail API

L'API Mail transforme vos e-mails en messages : vous envoyez un mail à l'adresse de votre configuration, nous l'analysons à l'aide de vos motifs et envoyons le résultat sous forme de SMS, RCS, WhatsApp ou message vocal. L'endroit où figurent le destinataire, le texte et l'expéditeur dans le mail, vous le décrivez une seule fois dans la configuration. Les destinataires peuvent être des numéros, des contacts ou des groupes de votre carnet d'adresses.

Adresse fixe avec motifs de mail

Chaque configuration de l'API Mail dispose d'une adresse fixe générée par le système et de trois motifs. Les motifs décrivent à quoi ressemblent vos mails : où se trouve le destinataire, où se trouve le texte du message et ce que le mail contient par ailleurs. L'API Mail s'adapte ainsi à votre application. La configuration elle-même se crée comme décrit dans la section Configuration.

Structure de l'adresse

L'adresse se compose d'un token fixe et d'un préfixe optionnel devant :

TOKEN@gateway.seven.io
PREFIX.TOKEN@gateway.seven.io

Le TOKEN est généré par nos soins, il est fixe et s'affiche dans votre espace de connexion sous Développeur > Mail API. Le PREFIX, c'est vous qui le choisissez pour chaque mail : tout ce qui précède le dernier point de la partie locale constitue le préfixe et est analysé au moyen du motif du préfixe d'adresse.

Ainsi, dans l'adresse 01761234567890.a1b2c3d4e5f6g7h8@gateway.seven.io, a1b2c3d4e5f6g7h8 est le token et 01761234567890 le préfixe.

Adresse courte sans token

Si l'option Vérifier l'expéditeur via DMARC est activée dans la configuration, le token peut être omis : un mail adressé à 01761234567890@gateway.seven.io est alors rattaché à la configuration uniquement par votre adresse d'expéditeur, et toute la partie locale de l'adresse constitue le préfixe. Seuls les expéditeurs prouvés comptent ici (voir Sécurité). Si plusieurs configurations contiennent le même expéditeur prouvé, aucune n'est utilisée ; une adresse prouvée prime sur une entrée de domaine prouvée. L'adresse avec token continue de fonctionner dans tous les cas.

Configuration en quatre étapes

La boîte de dialogue sous Développeur > Mail API vous guide à travers les quatre étapes d'une configuration.

Variables

Les variables suivantes sont disponibles dans les motifs. Cette liste est exhaustive, il n'existe pas d'autres variables.

De base

Étendues : {{delay}}, {{type}}, {{label}}, {{foreign_id}}, {{unicode}}, {{flash}}, {{performance_tracking}}, {{get_replies}}

La signification et les valeurs autorisées de ces variables sont décrites dans la section Format classique, sous Paramètres, et s'appliquent ici sans changement. {{type}} remplace, pour le mail concerné, le type défini dans la configuration. {{get_replies}} accepte yes ou no : avec yes, nous envoyons le message depuis un numéro capable de recevoir des réponses, afin que le destinataire puisse répondre directement ; un expéditeur défini est alors remplacé.

WhatsApp : {{template}}, {{template_lang}}, {{header}}, {{body}}, {{buttons}}, {{media_url}}, {{media_type}}, {{caption}}

Ces variables remplissent les champs d'un message WhatsApp ; leur signification est décrite dans la section WhatsApp (WA).

L'authentification repose sur votre adresse d'expéditeur et sur le token contenu dans l'adresse ; il n'y a pas de clé.

Chaque variable ne peut apparaître qu'une seule fois au maximum dans l'ensemble des trois motifs. {{text}} doit être capturé par l'un des motifs et {{to}} doit être capturé ou défini via Destinataire fixe.

Comment nous analysons le mail

• Le motif du préfixe d'adresse doit couvrir l'intégralité du préfixe.
• Dans le sujet et le corps, nous recherchons le motif : le texte littéral doit apparaître et les variables capturent le texte intermédiaire.
• Un motif vide signifie que cette partie du mail est ignorée.
• Un expéditeur capturé est prioritaire sur Expéditeur du message, un destinataire capturé sur Destinataire fixe.
• Si un motif ne correspond pas à la partie concernée du mail, le message n'est pas envoyé.

Sécurité

La vérification de l'expéditeur s'applique sans changement : nous n'acceptons que les mails provenant de l'une des adresses d'expéditeur enregistrées dans la configuration concernée, ou d'une adresse d'un domaine qui y est enregistré (*@domaine).

Vérifier l'expéditeur via DMARC

Pour plus de sécurité, l'option Vérifier l'expéditeur via DMARC peut être activée par configuration. Nous n'acceptons alors un mail que si le domaine expéditeur (le domaine de l'adresse From) passe la vérification DMARC sur notre passerelle. Cela suppose un enregistrement DMARC pour votre domaine, accompagné de SPF ou DKIM ; un domaine sans enregistrement DMARC ne passe jamais la vérification. Les redirections ne posent pas de problème tant que la signature DKIM reste intacte.

L'option ne peut être activée qu'une fois chaque expéditeur de la configuration prouvé. Vous prouvez une adresse d'expéditeur en envoyant depuis celle-ci, à l'adresse de test de la configuration, un mail de test qui passe la vérification DMARC. Vous prouvez une entrée de domaine (*@domaine) par un enregistrement TXT seven-mail-api-verify=TOKEN sur le domaine ; nous revérifions l'enregistrement chaque jour et retirons la preuve s'il manque pendant quelques jours. Les entrées de domaine ne sont pas possibles pour les domaines de messagerie gratuite, et une adresse d'expéditeur prouvée dans un compte ne peut plus être enregistrée dans un autre compte.

Un mail rejeté apparaît avec le code 904 dans votre Debugger. Dans ce cas, un mail d'erreur est envoyé exclusivement à l'adresse d'erreur enregistrée et jamais à l'expéditeur du mail, celui-ci pouvant être usurpé.

Exemples

Configuration par défaut

Sans adapter les motifs, l'ensemble du corps devient le texte du message. Le destinataire est défini dans la configuration et le mail part vers l'adresse sans préfixe.

Résultat : un SMS au 01761234567890 avec le texte « Votre colis est en route. » Le sujet est ignoré.

Destinataire dans l'adresse

Si chaque mail doit partir vers un numéro différent, capturez le destinataire avec {{to}} dans le préfixe de l'adresse. Un destinataire fixe n'est alors pas nécessaire.

Résultat : un SMS au 01761234567890 avec le texte « Votre colis est en route. »

Alerte dans l'objet, destinataire fixe

Un outil de monitoring envoie son alerte dans l'objet à une adresse fixe. Le destinataire est défini dans la configuration.

Résultat : un SMS au 01761234567890 avec le texte « Charge CPU critique sur srv-07 ».

Motif avec ancres

Si le mail contient autre chose que le seul texte du message, délimitez celui-ci par du texte littéral. Ici, deux paires de parenthèses encadrent le texte, suivies de la date d'envoi.

Résultat : un SMS au 01761234567890 avec le texte « Votre commande est en route. », programmé pour le 15 janvier 2027 à 08h00. La date de l'exemple représente n'importe quel moment futur que votre application définit elle-même.

Traitement des erreurs

Si un motif ne correspond pas à la partie concernée du mail ou si le destinataire reste vide, le message n'est pas envoyé. Vous recevez un mail d'erreur indiquant le motif, à condition d'avoir activé l'option « Notifier en cas d'erreurs ». Si Vérifier l'expéditeur via DMARC est activé, il en va de même pour les mails dont le domaine expéditeur échoue à la vérification DMARC ; ce mail d'erreur n'est envoyé qu'à l'adresse d'erreur.

Configuration

Dans votre espace de connexion sous Développeur dans Mail API, vous gérez vos configurations. L'icône verte + en bas à droite en crée une nouvelle ; la boîte de dialogue vous guide à travers les quatre étapes décrites plus haut. Vous pouvez créer autant de configurations que vous le souhaitez, chacune avec ses propres expéditeurs autorisés, sa propre adresse fixe et ses propres motifs. Les configurations nouvellement créées sont utilisables immédiatement après l'enregistrement.

En cliquant sur les engrenages bleus, vous accédez aux options de configuration pour l'API Mail.

Paramètres de l'API Mail

• Longueur maximale : Définissez un nombre maximal de caractères pour éviter les messages trop longs en raison de l'envoi de signatures. Entrez 0 pour désactiver cette fonction.
• Supprimer les citations : Si activé, l'API essaie automatiquement de supprimer le texte cité dans le mail.
• Notifier en cas d'erreur : Cette option détermine si vous souhaitez recevoir une notification par mail en cas d'erreurs. Par exemple, si l'envoi du message échoue, si un motif ne correspond pas à votre mail ou si des données comme le destinataire manquent, nous vous enverrons directement un mail avec une information sur l'erreur. Lors de la création d'une configuration, vous pouvez indiquer une adresse mail alternative pour recevoir les messages d'erreur.
• Insérer l'expéditeur du mail dans le texte : Ici, vous pouvez définir si vous souhaitez envoyer une partie de l'adresse mail au début de votre message. Vous pouvez choisir entre trois options :

Format classique

Les configurations créées avant l'introduction de l'adresse fixe fonctionnent au format classique : le destinataire figure dans la partie locale de l'adresse et les paramètres dans le sujet. Elles sont signalées comme Legacy dans le dashboard et continuent de fonctionner sans changement et sans limite dans le temps. Les nouvelles configurations utilisent des motifs de mail.

Structure du mail

Les mails adressés à une configuration Legacy ont la structure décrite ci-dessous. Les nouvelles configurations utilisent l'adresse fixe avec motifs de mail.

Destinataire

Pour envoyer un message via l'API Mail, envoyez un mail à destinataire@gateway.seven.io en remplaçant destinataire par le numéro du destinataire ou par le nom de contact de votre carnet d'adresses.

Par exemple, si vous souhaitez envoyer un message au numéro 01761234567890, le destinataire doit être 01761234567890@gateway.seven.io.

Sujet

Dans le sujet, entrez les paramètres nécessaires pour contrôler l'envoi du message. Ceux-ci doivent être séparés par un espace. Pour définir un paramètre, écrivez le nom du paramètre, suivi d'un signe égal et de la valeur du paramètre.

Par exemple, avec unParametre=uneValeur, le paramètre unParametre est défini sur uneValeur. Si le paramètre contient des espaces, vous devez l'entourer de guillemets doubles " – par exemple unParametre="Une valeur avec espaces".

Contenu

Le texte du message doit être envoyé dans le corps de l'e-mail. La passerelle utilise d'abord la partie text/plain du mail. Si le mail ne contient qu'une partie text/html sans alternative texte, elle tentera de l'analyser et d'extraire la partie texte du contenu HTML. Naturellement, cette méthode ne fonctionne pas toujours comme souhaité.

Vous pouvez entourer le texte du message avec ## pour empêcher que des lignes vides ou la signature de l'e-mail ne soient incluses dans le message. Le texte ressemblerait alors à ceci : ##Ceci est le texte## - seule la partie entre ##...## sera envoyée dans le message.

Paramètres

Tous les paramètres sont indiqués dans l'objet de l'e-mail comme mentionné ci-dessus. Si vous ne pouvez pas modifier l'objet de l'e-mail, vous pouvez également indiquer les paramètres dans l'adresse du destinataire comme suit :

• 01761234567890.from=ZahnPraxis@gateway.seven.io
• 01761234567890.from=ZahnPraxis.type=rcs@gateway.seven.io
• key=MAIL_API_KEY.from=ZahnPraxis.to=01761234567890@gateway.seven.io

Voici un aperçu des paramètres possibles :

WhatsApp (WA)

L'API Mail envoie également des messages WhatsApp. Dans une configuration avec motifs de mail, réglez le type sur WhatsApp et indiquez votre ID du service WhatsApp Frontend (Format : WA-XXXXXXXX) comme expéditeur du message ; dans une configuration Legacy, définissez type=WA et le paramètre from. Vous trouverez l'ID dans votre tableau de bord seven.io sous WABA → Services. Les champs suivants sont disponibles dans les deux cas : comme variables dans les motifs ou comme paramètres dans le sujet.

Types de messages WhatsApp

WhatsApp prend en charge trois types de messages, déterminés automatiquement en fonction des paramètres :

si template != null:
    → Message template
sinon si media_url != null:
    → Message multimédia
sinon:
    → Message texte (corps de l'e-mail)

Messages template

Les messages template sont nécessaires pour les messages en dehors de la fenêtre de 24h et doivent être préalablement approuvés par WhatsApp.

Messages multimédias

Les messages multimédias ne peuvent être envoyés que dans la fenêtre de conversation de 24h.

Messages texte

Pour les messages texte simples dans la fenêtre de 24h, le corps de l'e-mail est utilisé comme message.

Exemples WhatsApp (format classique)

1. Message template (en dehors de la fenêtre de 24h)

À: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.template=order_confirmation.template_lang=fr_FR.body=Jean,12345@gateway.seven.io

2. Template avec image d'en-tête

À: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.template=promo_image.header=https://example.com/promo.jpg.body=20%25-reduction@gateway.seven.io

3. Message texte (dans la fenêtre de 24h)

À: 491512345678.MYKEY.type=WA.from=WA-5AAB129C@gateway.seven.io

4. Envoyer une image (dans la fenêtre de 24h)

À: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.media_type=image.media_url=https://example.com/produit.jpg.caption=Votre-produit@gateway.seven.io

5. Envoyer un document

À: 491512345678.MYKEY.type=WA.from=WA-5AAB129C.media_type=document.media_url=https://example.com/facture.pdf.caption=Votre-facture@gateway.seven.io

Sécurité

Le chemin de transport entre les différents serveurs SMTP ou le client SMTP est généralement chiffré par TLS. Pour plusieurs raisons, il est toutefois judicieux de chiffrer le courrier, c'est pourquoi l'API Mail prend en charge le chiffrement via PGP et S/MIME :

1. Confidentialité : PGP et S/MIME chiffrent le contenu des e-mails, de sorte que seul le destinataire prévu peut les déchiffrer et les lire. Cela garantit la confidentialité de la communication.

2. Authentification : Les deux normes permettent de vérifier l'identité de l'expéditeur. Les signatures numériques, créées avec la clé privée de l'expéditeur, permettent au destinataire de s'assurer que l'e-mail provient bien de la source indiquée et n'a pas été altéré.

3. Intégrité : PGP et S/MIME offrent des mécanismes pour vérifier l'intégrité des e-mails. Grâce aux signatures numériques, le destinataire peut s'assurer que le contenu de l'e-mail n'a pas été modifié depuis son envoi.

4. Protection contre les attaques de type Man-in-the-Middle : Grâce au chiffrement et à l'authentification, PGP et S/MIME aident à prévenir les attaques de type Man-in-the-Middle, où un attaquant intercepte, manipule et retransmet le trafic sans que les parties impliquées ne s'en aperçoivent.

Dans l'ensemble, PGP et S/MIME sont donc utiles pour garantir la sécurité, la confidentialité et l'intégrité des communications par e-mail, en particulier dans les environnements où des informations sensibles ou confidentielles sont échangées.

Pour un envoi chiffré des e-mails, veuillez télécharger le certificat correspondant et l'installer dans votre système. Étant donné que les certificats PGP et S/MIME ne peuvent être liés qu'à une seule adresse e-mail, veuillez envoyer vos e-mails à l'adresse e-mail indiquée ci-dessous pour le certificat.

Le destinataire et les autres données s'indiquent, comme dans le format classique, via les paramètres correspondants dans l'objet, par exemple to=017612345678.

Vous pouvez télécharger le certificat correspondant ici :

DMARC, DKIM, SPF

DKIM, SPF et DMARC sont des mécanismes pour améliorer la sécurité des e-mails. Ils aident à vérifier l'authenticité des e-mails, à lutter contre le spam et le phishing, ainsi qu'à améliorer la délivrabilité des e-mails.

Notre passerelle vérifie chaque mail entrant au regard de SPF, DKIM et DMARC. Par défaut, le résultat est purement informatif : ce qui décide de l'acceptation reste la comparaison avec les adresses d'expéditeur enregistrées. Ce n'est qu'avec l'option Vérifier l'expéditeur via DMARC dans votre configuration Mail API que les mails dont le domaine expéditeur échoue à la vérification DMARC sont rejetés (code 904, voir Sécurité ci-dessus). Vous pouvez consulter les mails rejetés dans votre Debugger.

Exemples du format classique

Premier exemple

Dans le premier exemple, un SMS est envoyé au numéro 0163123456789 par l'expéditeur ZahnPraxis. La clé est dans ce cas email2sms_key.

Le texte à transmettre dans le SMS est :

Bonjour Monsieur Schubert, nous souhaitons vous rappeler votre rendez-vous le 20 janvier dans notre cabinet. Nous avons hâte de vous voir ! À bientôt, votre cabinet dentaire

Deuxième exemple

Dans ce deuxième exemple, un SMS est envoyé au contact Bartscher de l'expéditeur Opticien. Le numéro par défaut 0163123456789, qui figure dans le destinataire du mail, est remplacé par le paramètre to. La clé ici est 123456789.

Le texte à transmettre dans le SMS est le suivant :

Bonjour Madame Bartscher, vos lunettes sont prêtes ! Veuillez venir les récupérer prochainement chez nous. Nous avons hâte de vous voir ! À bientôt, votre opticien – la signature du mail ci-dessous ne sera pas envoyée dans le SMS, car le texte est encadré par ##.

Troisième exemple

Dans cet exemple, un SMS est envoyé au numéro 0163123456789. Les paramètres de l'expéditeur sont tirés des paramètres par défaut de votre compte sous Paramètres > SMS. La clé est ici directement intégrée dans le destinataire du mail et définie sur abcd123456.

Le texte à transmettre dans le SMS est le suivant :

Bonjour Madame Bartscher, vos lunettes sont prêtes ! Veuillez venir les récupérer prochainement chez nous. Nous avons hâte de vous voir ! À bientôt, votre opticien

La signature du mail ci-dessous ne sera pas envoyée dans le SMS, car le texte est encadré par ##.

Legacy

Pour des raisons de compatibilité descendante, l'API Mail reste disponible à l'ancienne adresse de destinataire email2sms@sms77.de pour les mails au format de l'époque. Les mails continueront d'être traités comme d'habitude. Cependant, nous recommandons de passer à une configuration avec adresse fixe et motifs de mail pour profiter de toutes les fonctionnalités.