Mail API
L'API Mail vous permet d'envoyer des SMS, RCS et bientôt des messages vocaux via seven par mail. Envoyez un mail à la passerelle, qui sera automatiquement converti en message par nos soins. Grâce à de nombreux paramètres, vous pouvez contrôler l'envoi de manière ciblée et envoyer des messages à des contacts ou des groupes.
Configuration
Dans votre espace de connexion sous Développeur dans Mail API, vous pouvez configurer l'API pour votre compte. Vous pouvez indiquer autant d'adresses d'expéditeur que vous le souhaitez, chacune avec une clé différente.
- 1
Configurer l'adresse de l'expéditeur
Cliquez sur l'icône verte + en bas à droite dans la section Mail API pour accéder à la fenêtre où vous pouvez créer une nouvelle adresse d'expéditeur.
- 2
Définir la clé
Vous devriez choisir une clé pour chaque adresse mail afin de sécuriser l'envoi. Vous pouvez choisir librement la clé, mais seules les lettres majuscules et minuscules, les chiffres et les caractères spéciaux tiret, soulignement et signe dollar sont autorisés.
- 3
Gestion des erreurs
Vous pouvez également indiquer une adresse mail optionnelle pour recevoir les messages d'erreur. Si vous ne l'indiquez pas, vous recevrez les messages d'erreur sur l'adresse de l'expéditeur si vous activez la fonction « Notifier en cas d'erreurs » dans les paramètres (voir ci-dessous). Les expéditeurs nouvellement configurés sont utilisables immédiatement après l'enregistrement.
- 4
Paramètres
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 ou si des données comme le numéro, la clé, etc. sont incorrectement indiquées ou manquantes dans votre e-mail, nous vous enverrons directement un mail avec une information sur l'erreur. Lors de la création d'une nouvelle adresse d'expéditeur, 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 :
| Paramètres | Explication |
|---|---|
| Adresse complète | Insère l'adresse complète, par exemple "unutilisateur@domaine.fr" |
| Partie locale de l'adresse | Par exemple, pour unutilisateur@domaine.fr, "unutilisateur" est inséré |
| Non | N'envoie pas l'adresse de l'expéditeur |
Envoyer un message
Structure du mail
Veuillez utiliser le format décrit ci-dessous pour vos mails à notre passerelle. Si votre application ne peut pas être ajustée pour envoyer des mails dans ce format, contactez-nous – l'API Mail est flexible et adaptable !
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.io01761234567890.from=ZahnPraxis.type=rcs@gateway.seven.iokey=MAIL_API_KEY.from=ZahnPraxis.to=01761234567890@gateway.seven.io
Voici un aperçu des paramètres possibles :
- Name
key- Type
- string
- Optional
- Optional
- Description
- La clé d'accès que vous avez indiquée dans vos paramètres Mail-API pour l'e-mail de l'expéditeur concerné.
- Name
from- Type
- string
- Optional
- Optional
- Description
- L'expéditeur du message. Si rien n'est indiqué ici, l'expéditeur par défaut de vos paramètres SMS sera utilisé. Jusqu'à 11 caractères alphanumériques ou jusqu'à 16 caractères numériques sont possibles.
- Name
to- Type
- string
- Optional
- Optional
- Description
- Le destinataire du message. Ce paramètre remplace, si
indiqué, le destinataire indiqué dans l'adresse du destinataire de l'e-mail. Vous pourriez par exemple
envoyer un e-mail à acme-inc@gateway.seven.io avec le paramètre
to=0176123456789. Le message sera envoyé à 0176123456789.
- Name
label- Type
- string
- Optional
- Optional
- Description
- Définissez éventuellement une étiquette propre à chaque
message pour pouvoir les classer dans vos statistiques. Si non indiqué, l'expéditeur de l'e-mail sera
automatiquement utilisé comme étiquette. Caractères autorisés :
a-z, A-Z, 0-9, .-_@
- Name
text- Type
- string
- Optional
- Optional
- Description
- Si vous ne pouvez pas placer le texte du message dans le
contenu de l'e-mail, vous pouvez l'entrer via le paramètre
textdans l'objet.
- Name
flash- Type
- boolean
- Optional
- Optional
- Description
- Envoyez un SMS Flash, qui s'affiche directement sur l'écran du destinataire et n'est pas enregistré. Uniquement pour le type de message SMS.
- Name
unicode- Type
- boolean
- Deprecated
- Deprecated
- Optional
- Optional
- Description
- Permet le codage du message en Unicode ou force GSM 03.38.
- Name
performance_tracking- Type
- boolean
- Optional
- Optional
- Description
- Active notre raccourcisseur d'URL et le suivi des performances pour les liens trouvés dans le texte.
- Name
foreign_id- Type
- string
- Optional
- Optional
- Description
- Indiquez votre propre ID pour ce message. Vous recevrez à nouveau le foreign_id lors des rappels pour les rapports de statut, etc. Max. 64 caractères, caractères autorisés :
a-z, A-Z, 0-9, .-_@.
- Name
delay- Type
- string
- Optional
- Optional
- Description
- Planifie l'envoi différé du message dans le futur. Indiquez ici soit un timestamp Unix soit le moment au format AAAA-MM-JJ hh:mm:ss.
- Name
type- Type
- enum
- Optional
- Optional
- Description
- Définissez le type de message que vous souhaitez envoyer. Les options possibles sont
sms(standard),rcset bientôtvoice.
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 :
-
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.
-
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é.
-
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.
-
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.
Les données telles que le destinataire du message doivent être spécifiées dans l'objet via les paramètres respectifs, comme 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.
L'API Mail rejette les mails s'ils ne respectent pas les standards d'authentification définis par votre configuration pour DKIM, SPF et DMARC. Cela peut être le cas, par exemple, si un e-mail ne possède pas de signature DKIM valide, si l'adresse IP de l'expéditeur n'est pas autorisée dans les enregistrements SPF, ou si les politiques DMARC du propriétaire du domaine prévoient le rejet des e-mails non authentifiés.
Veuillez en tenir compte lors de l'implémentation de l'API Mail. Vous pouvez consulter les mails rejetés dans votre Debugger.
Exemples
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 à cette nouvelle API pour profiter de toutes les fonctionnalités.
Il semble que vous n'ayez pas encore collé le contenu Markdown. Veuillez le coller, et je vous aiderai avec la traduction.