Débuter avec le courrier électronique

La Messages API prend en charge l'e-mail en tant que canal, ce qui vous permet d'envoyer des e-mails transactionnels en utilisant le même contrat d'API que celui que vous utilisez déjà pour d'autres canaux de messagerie.

Le canal Email est actuellement en phase bêta. Pendant cette phase, l'onboarding est géré par votre Account Manager.

Conditions préalables

Avant de commencer, assurez-vous d'avoir

  • A Compte API Vonage
  • Votre clé API et votre secret API, disponibles dans le tableau de bord de l'API Vonage
  • Un domaine d'expédition que vous pouvez gérer dans le DNS
  • Accès bêta au canal « E-mail »

L'intégration par courrier électronique (Onboarding)

Pour commencer à utiliser l'API Email :

  1. Fournissez les informations suivantes à votre Account Manager :
    • Votre clé API Vonage
    • Le ou les domaines personnalisés que vous prévoyez d'utiliser pour l'envoi (par exemple, yourdomain.com)
    • Votre région préférée pour la vérification du nom de domaine (US, EUou APAC)
  2. Votre Account Manager transmet ces informations à l'équipe interne afin de lancer la procédure d'intégration.
  3. Vonage vous fournit les enregistrements DNS que vous devez ajouter à votre domaine. Voir Configuration de l'authentification du domaine.
  4. Une fois la mise à jour du DNS effectuée, vérifiez que tout s'est bien passé auprès de votre Account Manager. La vérification du DNS peut prendre jusqu'à 72 heures.
  5. Ajoutez les enregistrements DNS sans tarder. Si la propagation prend plus de temps que prévu, ouvrez un ticket d'assistance ou contactez votre Account Manager.
  6. Une fois la vérification effectuée avec succès, Vonage en informe votre responsable de compte et vous pouvez commencer à envoyer des e-mails via la Messages API.

Pendant la phase bêta, un domaine ne peut être vérifié que dans une seule région. Choisissez la région la plus proche de vos utilisateurs ou de votre infrastructure.

Configuration de l'authentification du domaine

Avant de pouvoir envoyer des e-mails, vous devez authentifier votre domaine d'envoi. L'authentification du domaine améliore le taux de délivrabilité et permet aux fournisseurs de messagerie de vérifier que Vonage est autorisé à envoyer des e-mails en votre nom.

L'authentification s'effectue en ajoutant des enregistrements DNS à votre domaine. Ces enregistrements permettent :

  • SPF (Sender Policy Framework) pour autoriser l'infrastructure d'envoi de Vonage.
  • DKIM (DomainKeys Identified Mail) pour signer cryptographiquement le contenu des e-mails sortants.
  • DMARC (Domain-based Message Authentication, Reporting and Conformance) pour définir la politique et les rapports en cas d'échecs d'authentification.

Les principaux fournisseurs de messagerie, notamment Google, Microsoft et Yahoo, se basent sur ces normes pour déterminer s'ils doivent acheminer, rejeter ou filtrer les messages.

Pour plus d'informations, voir Facteurs influant sur la délivrabilité de vos e-mails.

Enregistrements DNS à configurer

Vonage fournit les valeurs exactes lors de la mise en service. Le tableau ci-dessous présente la structure attendue des enregistrements :

Objectif Type Hôte / Clé Valeur Description
AUTH CNAME <dkim_key_1>._domainkey.<your_domain> <dkim_value_1>._domainkey.xxxx.com Clé DKIM n° 1
AUTH CNAME <dkim_key_2>._domainkey.<your_domain> <dkim_value_2>._domainkey.xxxx.com Clé DKIM n° 2
AUTH CNAME <dkim_key_3>._domainkey.<your_domain> <dkim_value_3>._domainkey.xxxx.com Clé DKIM n° 3
SEND TXT _dmarc.<your_domain> v=DMARC1; p=none; Politique DMARC
SEND TXT <your_domain> v=spf1 include:msg.vonage.com ~all Politique relative au SPF

Bonnes pratiques en matière d'authentification

  • Configurez tous les enregistrements DKIM fournis par Vonage pour chaque domaine d'envoi.
  • Commencez par DMARC p=none pendant la phase de suivi, puis appliquez des règles plus strictes lorsque vous serez prêt.
  • Ajoutez Vonage à votre enregistrement SPF à l'aide de include:msg.vonage.com.
  • Si vous disposez déjà d'un enregistrement SPF, ajoutez l'inclusion Vonage à la fin de celui-ci, sans remplacer les entrées existantes.

Exemple :

  • SPF actuel : v=spf1 include:example.com ~all
  • Indice SPF mis à jour : v=spf1 include:example.com include:msg.vonage.com ~all

Options DNS avancées

  • Cliquez ici pour ouvrir le DNS de suivi : Vonage peut fournir des enregistrements CNAME supplémentaires pour la configuration du suivi.
  • Personnalisé mail from / return-path : Vonage prend en charge la configuration personnalisée du return-path et peut fournir des enregistrements MX et TXT supplémentaires.

Si vous avez besoin de ces options avancées lors de votre intégration, n'hésitez pas à en parler à votre Account Manager.

Envoyez votre premier courriel

Une fois votre domaine vérifié, vous pouvez commencer à envoyer des e-mails à l'aide de la Messages API.

Créer une application Vonage (facultatif)

Pour utiliser la Messages API, vous devez disposer d'une application Vonage sur laquelle la fonctionnalité Messages est activée.

  1. Aller à Créer une application dans le tableau de bord de Vonage.
  2. Saisissez le nom d'une application.
  3. Cliquez sur Générer une clé publique et une clé privée et conservez la clé privée en lieu sûr.
  4. Sous Capacités, activer Messages.
  5. Configurez vos webhooks « URL d'arrivée » et « URL d'état ».
  6. Cliquez sur Générer une nouvelle application.

Pour plus d'informations, voir Créer une application Vonage.

Définissez vos valeurs remplaçables

Utilisez les variables suivantes dans les exemples et remplacez-les par vos propres valeurs :

Variable Description
VONAGE_API_KEY Votre clé API Vonage, disponible dans le tableau de bord de l'API.
VONAGE_API_SECRET Votre secret API Vonage.
VONAGE_APPLICATION_ID Votre identifiant d'application Vonage.
VONAGE_PRIVATE_KEY Chemin d'accès à votre fichier de clé privée.
FROM_EMAIL Votre adresse e-mail d'expéditeur vérifiée.
TO_EMAIL Adresse e-mail du destinataire.
EMAIL_SUBJECT Objet de l'e-mail.

Générer un JWT

La Messages API utilise l'authentification JWT. Générez un JWT à l'aide de votre identifiant d'application et de votre clé privée avant d'appeler l'API.

Envoyer un message texte

{
   "channel": "email",
   "from": "sender@example.com",
   "to": "recipient@example.com",
   "message_type": "text",
   "text": "Email body text",
   "email": {
      "subject": "Email subject"
   }
}

En cas de réussite, la réponse de l'API contient message_uuid:

{
   "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Envoyer un courriel HTML

{
   "channel": "email",
   "from": "sender@example.com",
   "to": "recipient@example.com",
   "message_type": "html",
   "html": {
      "body": "<p>Email body html</p>"
   },
   "email": {
      "subject": "Email subject"
   }
}

Limites de taille des courriels

Le corps de l'e-mail peut atteindre 100 Ko par requête API. Si le corps dépasse cette limite, la requête renvoie une erreur.

La Messages API impose également une limite de taille de charge utile de 200 Ko au niveau du réseau.

Vérifier l'état de la livraison

Une fois l'e-mail envoyé, Vonage envoie des mises à jour sur le statut du message à l'URL de statut que vous avez configurée.

Statut Description
submitted L'e-mail a été accepté et mis en file d'attente pour livraison.
delivered L'e-mail a été remis dans la boîte de réception du destinataire.
read Le destinataire a ouvert l'e-mail.
rejected L'e-mail n'a pas pu être remis. Vérifiez les détails de l'erreur.

Facteurs influençant la délivrabilité de vos e-mails

La délivrabilité des e-mails désigne la capacité d'un message électronique à parvenir dans la boîte de réception du destinataire.

Delivery et deliverability sont différentes :

  • La « remise » signifie que le serveur de messagerie destinataire a accepté le message.
  • La délivrabilité désigne le fait que le message arrive dans la boîte de réception et non dans le dossier « spam » ou qu'il ne soit pas rejeté.

Modèle de responsabilité partagée

La délivrabilité des e-mails relève d'une responsabilité partagée entre Vonage et le client.

Responsabilités de Vonage Responsabilités du client
Une infrastructure de distribution des e-mails fiable Envoi d'e-mails pertinents et attendus
Plateforme à haute disponibilité Gestion des listes de destinataires
Traitement des messages Authentification des domaines d'origine
Traitement des messages non remis et des réclamations Respecter les bonnes pratiques en matière d'e-mails
Gestion de la liste de suppression Suivi des indicateurs d'engagement

1. Authentification du domaine

L'authentification du domaine est l'un des facteurs les plus importants pour la délivrabilité.

  • Le protocole DKIM signe le contenu du message.
  • DMARC définit la politique à suivre en cas d'échec de l'authentification.
  • Le SPF autorise les expéditeurs approuvés.

Ces normes permettent aux fournisseurs de messagerie de vérifier l'identité de l'expéditeur et l'intégrité des messages.

2. Réputation de l'expéditeur

Les fournisseurs de messagerie évaluent en permanence la réputation des domaines et des adresses IP.

Une mauvaise réputation peut entraîner :

  • Placement dans le dossier « Spam »
  • Limitation temporaire du débit
  • Rejet d'un message
  • Meilleur placement dans la boîte de réception

La réputation dépend des plaintes pour spam, des taux de rebond, de la régularité des envois, de l'engagement des utilisateurs et de la qualité des messages.

Meilleures pratiques :

  • N'envoyez vos messages qu'aux destinataires qui les attendent.
  • Évitez les pics soudains de volume d'envoi.
  • Supprimez régulièrement les destinataires inactifs.
  • Surveillez les taux de rebond et de réclamation.

3. Qualité du contenu des e-mails

Les fournisseurs de messagerie évaluent également la qualité du contenu des messages.

Les liens rompus, les pièces jointes suspectes, un contenu composé exclusivement d'images ou des messages trop volumineux peuvent nuire à la délivrabilité.

Meilleures pratiques :

  • Utilisez des domaines de confiance dans vos liens.
  • Veillez à ce que le contenu de vos messages soit clair, pertinent et bien structuré.
  • Veillez à maintenir un bon équilibre entre le texte et les images.
  • Vérifiez les pièces jointes et veillez à ce que la taille des données ne dépasse pas les limites autorisées.

4. Implication des bénéficiaires

Les fournisseurs de messagerie utilisent les indicateurs d'engagement des destinataires pour déterminer le placement des e-mails dans la boîte de réception.

Les signaux positifs comprennent les ouvertures, les clics, les réponses et le fait de déplacer des messages du dossier « Spam » vers la boîte de réception. Les signaux négatifs comprennent les plaintes, la suppression immédiate et l'inactivité prolongée.

Un engagement plus élevé contribue généralement à améliorer la réputation de l'expéditeur.

5. Gestion des rebonds

Les « hard bounces » et les « soft bounces » ont des répercussions différentes sur la réputation de l'expéditeur.

  • Rebond définitif : échec irrémédiable (par exemple, adresse invalide ou destinataire inexistant).
  • Rebond souple : échec temporaire (par exemple, boîte de réception pleine ou problème temporaire du serveur).

Vonage traite automatiquement les événements de rebond et gère les règles de suppression afin de limiter les tentatives de livraison répétées auprès de destinataires dont les adresses sont définitivement inaccessibles.

6. Plaintes pour spam

Les plaintes pour spam comptent parmi les signaux de confiance négatifs les plus importants pris en compte par les fournisseurs de messagerie.

Des taux de réclamations élevés peuvent entraîner :

  • Meilleur placement dans la boîte de réception
  • Blocages temporaires
  • Atteinte irréversible à la réputation

Meilleures pratiques :

  • N'envoyez ces messages qu'aux utilisateurs qui ont donné leur accord.
  • Précisez clairement le nom de votre organisation.
  • Veillez à ce que la procédure de désabonnement soit simple et bien visible.
  • Répondez rapidement aux demandes de désabonnement.

Vonage traite les cas de spam et empêche leur renvoi aux destinataires concernés.

7. Qualité des annonces

Les listes de destinataires obsolètes, invalides ou achetées réduisent considérablement le taux de délivrabilité.

La qualité des listes se détériore :

  • Rejets définitifs
  • Plaintes pour spam
  • Désabonnements

Meilleures pratiques :

  • Collectez les adresses via des procédures d'inscription volontaire valides.
  • Supprimez rapidement les destinataires non valides.
  • Nettoyez régulièrement la liste des destinataires inactifs.
  • N'achetez jamais de listes d'adresses e-mail.

Tarification par courriel

La tarification de l'API de messagerie électronique repose sur un système d'abonnement et est proposée selon plusieurs niveaux. Chaque niveau comprend un nombre fixe d'e-mails, et des frais supplémentaires s'appliquent pour chaque e-mail supplémentaire.

Pour connaître les tarifs en vigueur, veuillez contacter votre Account Manager.

Plus d'informations