Débuter avec le courrier électronique

L'API Messages de Vonage prend en charge le courriel en tant que canal, ce qui vous permet d'envoyer des courriels transactionnels en utilisant le même contrat d'API que vous utilisez déjà pour d'autres canaux de messagerie. Avec une seule intégration, vous pouvez gérer toutes vos communications sortantes sans ajouter un fournisseur de courriel distinct à votre pile.

Ce guide vous présente tout ce dont vous avez besoin pour envoyer votre premier courrier électronique à l'aide de l'API Messages.

Conditions préalables

Avant de commencer, assurez-vous que vous disposez des éléments suivants :

• A Compte API Vonage
• Votre clé et votre secret d'API, disponibles sur le tableau de bord API de Vonage.
• Un domaine d'envoi vérifié - voir Configuration de l'authentification du domaine ci-dessous
• Accès Beta au canal Email - contactez votre Account Manager

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

Pour vous inscrire, suivez les étapes suivantes :

1. Fournissez les informations suivantes à votre Account Manager :
   • Votre clé API Vonage
   • Le(s) domaine(s) personnalisé(s) à partir duquel (desquels) vous enverrez des e-mails (par exemple, votredomaine.com)
   • Votre région préférée pour la vérification du domaine : US, EU, ou APAC

2. Votre Account Manager transmet les informations au Product Manager, qui lance le processus d'onboarding.
3. Vonage fournit un ensemble d'enregistrements DNS que vous devez ajouter à la configuration DNS de votre domaine. Voir Configuration de l'authentification du domaine pour obtenir la liste complète des enregistrements et la fonction de chacun d'entre eux.
4. Une fois que vous avez mis à jour vos enregistrements DNS, confirmez-les auprès de votre Account Manager. La vérification des DNS peut prendre jusqu'à 72 heures.
5. Ajoutez vos enregistrements DNS rapidement, la propagation peut prendre jusqu'à 72 heures. Si cela prend plus de temps que prévu, nous vous recommandons de générer de nouveaux enregistrements DNS pour votre domaine.
6. Une fois la vérification terminée, Vonage informe votre Account Manager et vous pouvez commencer à envoyer des e-mails via l'API Messages.

Configuration de l'authentification du domaine

Avant de pouvoir envoyer des courriels, vous devez authentifier votre domaine d'envoi. L'authentification du domaine améliore la délivrabilité des courriels et permet aux fournisseurs de boîtes aux lettres de vérifier que Vonage est autorisé à envoyer des courriels en votre nom.

L'authentification est complétée par l'ajout d'enregistrements DNS à la configuration DNS de votre domaine. Ces enregistrements permettent :

• SPF (Sender Policy Framework) - autorise l'infrastructure d'envoi de Vonage à envoyer des messages au nom de votre domaine.
• DKIM (DomainKeys Identified Mail) - signe cryptographiquement les courriels sortants afin que les serveurs de réception puissent vérifier que le contenu n'a pas été modifié.
• DMARC (Domain-based Message Authentication, Reporting & Conformance) - définit la politique de traitement des échecs d'authentification et fournit des rapports.

Les principaux fournisseurs de boîtes aux lettres, tels que Google, Microsoft et Yahoo, s'appuient sur ces mécanismes pour déterminer si les courriels doivent être délivrés, rejetés ou marqués comme spam.

Enregistrements DNS à configurer

Vonage fournit les valeurs exactes des enregistrements DNS lors de la formation initiale. Le tableau ci-dessous montre la structure et le type de chaque enregistrement que vous devrez ajouter :

Envoyez votre premier courriel

Une fois votre domaine vérifié, vous êtes prêt à envoyer des courriels via l'API Messages.

Créer une application Vonage

Pour utiliser l'API Messages, vous avez besoin d'une application Vonage dont la fonction Messages est activée. L'application contient votre configuration de webhook et vos identifiants d'authentification.

1. Allez à Créer une application dans le tableau de bord de Vonage.
2. Donnez un nom à votre application.
3. Cliquez sur Générer une clé publique et une clé privée. Votre fichier de clé privée se télécharge automatiquement - conservez-le en toute sécurité, car il ne peut pas être retéléchargé.
4. Sous Capacités, activer Messages.
5. Définissez l'URL entrante et l'URL d'état en fonction des points de terminaison du webhook dans votre application. Si vous ne les avez pas encore, vous pouvez utiliser des URL de remplacement et les mettre à jour ultérieurement.
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

Les exemples de code de ce guide utilisent les variables suivantes. Remplacez chacune d'entre elles par vos valeurs réelles avant d'exécuter les exemples.

Générer un JWT

L'API Messages utilise des jetons Web JSON (JWT) pour l'authentification. Générez un JWT à l'aide de votre identifiant d'application et de votre clé privée.

Envoyer un message texte

Utilisez la demande suivante pour envoyer un courriel en texte clair :

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

Si la demande aboutit, vous recevez une réponse contenant le code message_uuid:

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

Envoyer un courriel HTML

Pour envoyer un courrier électronique avec un contenu HTML, définissez message_type à "html" et fournissez votre balisage HTML dans le champ "body" :

{
  "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 du message a une taille maximale de 100 Ko par demande API. Si le corps du message dépasse cette limite, la demande renvoie une erreur. Veillez à ce que le corps de votre message ne dépasse pas la limite de taille autorisée.

Outre la limite du corps du message, l'API Messages applique une restriction au niveau du réseau sur la taille totale de la charge utile de 200 Ko. Gardez ces limites à l'esprit pour garantir une distribution fiable des messages.

Vérifier l'état de la livraison

Après avoir envoyé un courriel, Vonage envoie des mises à jour de l'état de la livraison à l'URL d'état configurée dans votre application Vonage. Chaque mise à jour est une requête POST contenant l'élément message_uuid et un champ d'état.

Les statuts clés pour le canal Email sont les suivants :

Tarification par courriel

La tarification d'Email API est basée sur l'abonnement et est disponible en six niveaux. Chaque niveau comprend un nombre fixe d'e-mails. Une fois que vous avez utilisé les courriels inclus dans votre plan, des frais de dépassement s'appliquent sur une base par courriel. Pour connaître les tarifs en vigueur, contactez votre Account Manager.

Plus d'informations

• Comprendre la messagerie électronique
• Référence de l'API Messages