Partager via

Hydratation de messageId en utilisant EmailClient

Cet article explique comment alimenter messageId à l’aide de EmailClient avec nos Kits de développement logiciel (SDK) de messagerie.

Commencez avec Azure Communication Services en utilisant la bibliothèque de client Communication Services .NET Email pour envoyer des e-mails.

Le fait d’effectuer les étapes de cet article entraîne un coût minime de quelques centimes de dollar USD ou moins sur votre compte Azure.

Conseil / Astuce

Démarrez rapidement votre expérience d’envoi de courrier électronique avec Azure Communication Services à l’aide de GitHub Exemples d’envoi de courrier de base et d’envoi de courrier électronique avancé.

Comprendre le modèle objet e-mail

Les classes et les interfaces suivantes gèrent certaines des principales fonctionnalités de la bibliothèque de client Azure Communication Services Email pour C#.

Nom Descriptif
Adresse e-mail Cette classe contient une adresse e-mail et une option pour un nom d’affichage.
Pièce jointe à l'email Cette classe crée une pièce jointe d’e-mail en acceptant un ID unique, une chaîne de pièce jointe d’e-mail de type MIME, des données binaires pour le contenu et un ID de contenu facultatif pour la définir en tant que pièce jointe inline.
EmailClient Cette classe est nécessaire pour toutes les fonctionnalités de messagerie. Vous l’instanciez avec vos chaîne de connexion et vous l’utilisez pour envoyer des e-mails.
Options du client de messagerie Cette classe peut être ajoutée à l’instanciation de EmailClient pour cibler une version d’API spécifique.
Contenu de l'email Cette classe contient l’objet et le corps de l’e-mail. Vous devez spécifier au moins un contenu PlainText ou Html
En-tête personnalisé de courriel Cette classe permet l’ajout d’une paire nom et valeur pour un en-tête personnalisé. L’importance de l’e-mail peut également être spécifiée par le biais de ces en-têtes à l’aide du nom d’en-tête « x-priority » ou « x-msmail-priority »
Message électronique Cette classe combine l’expéditeur, le contenu et les destinataires. Des en-têtes personnalisés, des pièces jointes et des adresses e-mail de réponse peuvent également être ajoutés.
Destinataires de courriel Cette classe contient des listes d’objets EmailAddress pour les destinataires de l’e-mail, y compris les listes facultatives pour les destinataires CC et BCC.
Opération d'envoi d'email Cette classe représente l’opération d’envoi de courrier asynchrone et est retournée à partir de l’appel d’API d’envoi de courrier électronique.
EmailSendResult Cette classe contient les résultats de l’opération d’envoi d’e-mail. Il a un ID d’opération, un état d’opération et un objet d’erreur (le cas échéant).

EmailSendResult renvoie l’état suivant sur l’opération de messagerie effectuée.

Statut Descriptif
NotStarted Nous n’envoyons pas ce statut à partir de notre service pour l’instant.
Course à pied L’opération d’envoi d’e-mail est en cours de traitement.
Réussi L’opération d’envoi par e-mail s’est terminée sans erreur et l’e-mail est en attente de remise. Tout état détaillé de la remise d’e-mail au-delà de cette étape peut être obtenu via Azure Monitor ou via Azure Event Grid. Découvrir comment s’abonner à des événements par e-mail
Échec L’opération d’envoi d’e-mail n’a pas réussi et a rencontré une erreur. L’e-mail n’a pas été envoyé. Le résultat contient un objet d’erreur avec des détails supplémentaires sur la cause de l’échec.

Prerequisites

Le fait d’effectuer les étapes de cet article entraîne un coût minime de quelques centimes de dollar USD ou moins sur votre compte Azure.

Note

Nous pouvons également envoyer un e-mail à partir de notre propre domaine vérifié. Ajouter des domaines personnalisés vérifiés à Email Communication Service.

Vérification du prérequis

  • Dans une fenêtre de terminal ou de commande, exécutez la commande dotnet pour vérifier que la bibliothèque de client .NET est installée.
  • Pour voir les sous-domaines associés à votre ressource Email Communication Services, connectez-vous au portail Azure, localisez votre ressource Email Communication Services, puis ouvrez l’onglet Provisionner des domaines dans le volet de navigation gauche.

Créer une application C#

Dans une fenêtre de console (par exemple cmd, PowerShell ou Bash), utilisez la commande dotnet new pour créer une application console avec le nom EmailQuickstart. Cette commande crée un projet C# « Hello World » simple avec un seul fichier source : Program.cs.

dotnet new console -o EmailQuickstart

Remplacez votre répertoire par le dossier d’application que vous venez de créer, puis utilisez la commande dotnet build pour compiler votre application.

cd EmailQuickstart
dotnet build

Installer le package

Dans le répertoire de l'application, installez le paquet de la bibliothèque cliente Azure Communication Services Email pour .NET en utilisant la commande dotnet add package.

dotnet add package Azure.Communication.Email

Création du client de messagerie avec l’authentification

Ouvrez Program.cs et remplacez le code existant par les instructions suivantes pour ajouter using des directives pour inclure l’espace Azure.Communication.Email de noms et un point de départ pour l’exécution de votre programme.


using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

using Azure;
using Azure.Communication.Email;

namespace SendEmail
{
  internal class Program
  {
    static async Task Main(string[] args)
    {

    }
  }
}

Vous avez quelques options disponibles pour l’authentification d’un client de messagerie :

Ouvrez Program.cs dans un éditeur de texte, puis remplacez le corps de la méthode Main par du code permettant d’initialiser un EmailClient avec votre chaîne de connexion. Le code suivant récupère la chaîne de connexion de la ressource à partir d’une variable d’environnement nommée COMMUNICATION_SERVICES_CONNECTION_STRING. Découvrez comment gérer la chaîne de connexion de la ressource.

// This code demonstrates how to fetch your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
EmailClient emailClient = new EmailClient(connectionString);

Hydratation de messageId en utilisant EmailClient

Vous pouvez activer un messageId (operationId) à l’aide de EmailClient pour suivre et gérer plus efficacement les opérations de messagerie. Ce processus est appelé « réalimentation » et vous permet de continuer à surveiller l’état d’un e-mail lorsque vous n’avez pas l’objet EmailSendOperation d’origine.

Créer le client de messagerie

// Create the EmailClient
var connectionString = "<ACS_CONNECTION_STRING>";
var emailClient = new EmailClient(connectionString);

Configurer les détails de l’e-mail

var sender = "<SENDER_EMAIL>";
var recipient = "<RECIPIENT_EMAIL>";
var subject = "Send email with manual status polling using operationID";

Créer du contenu de courrier électronique

var emailContent = new EmailContent(subject)
{
    PlainText = "This is plain text mail send test body \n Best Wishes!!",
    Html = "<html><body><h1>Quick send email test</h1><br/><h4>Communication email as a service mail send app working properly</h4><p>Happy Learning!!</p></body></html>"
};

var emailMessage = new EmailMessage(sender, recipient, emailContent);

Envoyer un e-mail et capturer l’ID d’opération

var emailSendOperation = await emailClient.SendAsync(
    wait: WaitUntil.Started,
    message: emailMessage);

// Get the OperationId so that it can be used for rehydrating an EmailSendOperation object
// and use that object to poll for the status of the email send operation.
var operationId = emailSendOperation.Id;
Console.WriteLine($"Email operation id = {operationId}");

operationId est l’identificateur de clé qui vous permet de réalimenter l’opération ultérieurement. Dans les applications réelles, vous stockez généralement cet ID pour référence ultérieure.

Réalimenter l’ID d’opération et interroger l’achèvement

// Poll for the status of the email send operation using the previous operationId
await PollForEmailSendOperationStatusWithExistingOperationId(emailClient, operationId);

private static async Task PollForEmailSendOperationStatusWithExistingOperationId(EmailClient emailClient, string operationId)
{
    // Rehydrate a new EmailSendOperation object using the given operationId
    // Rehydration refers to the process of creating a new EmailSendOperation object using the operation ID from a previous EmailSendOperation.
    // This is necessary in case you want to continue monitoring the status of the email manually, when you don't have 
    // the original EmailSendOperation object from the initial request.
    EmailSendOperation rehydratedEmailSendOperation = new EmailSendOperation(operationId, emailClient);

    // Call UpdateStatus on the rehydrated email send operation to poll for the status manually.
    try
    {
        while (true)
        {
            await rehydratedEmailSendOperation.UpdateStatusAsync();
            if (rehydratedEmailSendOperation.HasCompleted)
            {
                break;
            }
            await Task.Delay(100);
        }

        if (rehydratedEmailSendOperation.HasValue)
        {
            Console.WriteLine($"Email queued for delivery. Status = {rehydratedEmailSendOperation.Value.Status}");
        }
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"Email send failed with Code = {ex.ErrorCode} and Message = {ex.Message}");
    }
}

Exemple de code

Vous pouvez télécharger l’exemple d’application illustrant cette action à partir de GitHub Azure Samples Envoyer un e-mail avec interrogation manuelle à l'aide de l'ID d'opération.

Commencez avec Azure Communication Services en utilisant le SDK Communication Services Java Email pour envoyer des e-mails.

Suivre ce guide de démarrage rapide entraîne un coût minime de quelques cents USD tout au plus dans votre compte Azure.

Conseil / Astuce

Démarrez votre expérience d’envoi d’e-mails avec Azure Communication Services en passant directement à l’exemple de code Envoi de Email de base et Email d’envoi avancé sur GitHub.

Présentation du modèle objet de l’e-mail

Les classes et interfaces suivantes gèrent quelques-unes des principales fonctionnalités du kit de développement logiciel (SDK) Azure Communication Services Email pour Python.

Nom Descriptif
Adresse e-mail Cette classe contient une adresse e-mail et une option pour un nom d’affichage.
Pièce jointe à l'email Cette interface crée une pièce jointe par e-mail en acceptant un ID unique, une chaîne de pièce jointe d’e-mail de type MIME, une chaîne d’octets de contenu et un ID de contenu facultatif pour la définir en tant que pièce jointe inline.
EmailClient Cette classe est nécessaire pour toutes les fonctionnalités de messagerie. Vous l’instanciez avec vos chaîne de connexion et vous l’utilisez pour envoyer des e-mails.
Message électronique Cette classe combine l’expéditeur, le contenu et les destinataires. Des en-têtes personnalisés, des pièces jointes et des adresses e-mail de réponse peuvent également être ajoutés.
EmailSendResult Cette classe contient les résultats de l’opération d’envoi d’e-mail. Il a un ID d’opération, un état d’opération et un objet d’erreur (le cas échéant).
EmailSendStatus Cette classe représente l’ensemble des états d’une opération d’envoi d’e-mail.

EmailSendResult renvoie l’état suivant sur l’opération de messagerie effectuée.

Nom du statut Descriptif
NOT_STARTED Nous n’envoyons pas ce statut à partir de notre service pour l’instant.
IN_PROGRESS L’opération d’envoi d’e-mail est en cours de traitement.
ACCOMPLI AVEC SUCCÈS L’opération d’envoi d’e-mail s’est terminée sans erreur et l’e-mail est en attente de remise. Tout état détaillé de la remise d’e-mail au-delà de cette étape peut être obtenu via Azure Monitor ou via Azure Event Grid. Découvrir comment s’abonner à des événements par e-mail
ÉCHEC L’opération d’envoi d’e-mail n’a pas réussi et a rencontré une erreur. L’e-mail n’a pas été envoyé. Le résultat contient un objet d’erreur avec des détails supplémentaires sur la cause de l’échec.

Prerequisites

Le fait de suivre ce guide de démarrage rapide entraîne une petite dépense de quelques cents USD tout au plus dans votre compte Azure.

Note

Nous pouvons également envoyer un e-mail à partir de notre propre domaine vérifié Ajouter des domaines vérifiés personnalisés à Email Communication Service.

Vérification du prérequis

  • Dans une fenêtre de terminal ou de commande, exécutez mvn -v pour vérifier que Maven est installé.
  • Pour voir les domaines vérifiés avec votre ressource Email Communication Services, connectez-vous au portail Azure. Localisez votre ressource Email Communication Services, puis ouvrez l’onglet Provisionner des domaines dans le volet de navigation gauche.

Configurer l’environnement d’application

Pour configurer un environnement afin d’envoyer des e-mails, effectuez les étapes décrites dans les sections suivantes.

Créer une application Java

Ouvrez votre terminal ou votre fenêtre Commande, puis accédez au répertoire dans lequel vous souhaitez créer votre application Java. Exécutez la commande suivante pour générer le projet Java à partir du modèle maven-archetype-quickstart.

mvn archetype:generate -DarchetypeArtifactId="maven-archetype-quickstart" -DarchetypeGroupId="org.apache.maven.archetypes" -DarchetypeVersion="1.4" -DgroupId="com.communication.quickstart" -DartifactId="communication-quickstart"

L’objectif generate crée un répertoire qui porte le même nom que la valeur artifactId. Sous ce répertoire, le répertoire src/main/java contient le code source du projet, le répertoire src/test/java contient la source de test et le fichier pom.xml est le modèle objet du projet (POM, Project Object Model).

Installer le package

Ouvrez le fichier pom.xml dans votre éditeur de texte. Ajoutez l’élément dépendance suivant au groupe de dépendances.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-email</artifactId>
    <version>1.0.0-beta.2</version>
</dependency>

Configurer le framework d’application

Ouvrez /src/main/java/com/communication/quickstart/App.java dans un éditeur de texte, ajoutez des directives d’importation, puis supprimez l’instruction System.out.println("Hello world!"); :

package com.communication.quickstart;

import com.azure.communication.email.models.*;
import com.azure.communication.email.*;
import com.azure.core.util.polling.PollResponse;
import com.azure.core.util.polling.SyncPoller;

public class App
{
    public static void main( String[] args )
    {
        // Quickstart code goes here.
    }
}

Création du client de messagerie avec l’authentification

Il existe différentes options disponibles pour authentifier un client de messagerie :

Pour authentifier un client, vous instanciez un EmailClient avec votre chaîne de connexion. Découvrez comment gérer la chaîne de connexion de la ressource. Vous pouvez aussi initialiser le client avec n’importe quel client HTTP personnalisé qui implémente l’interface com.azure.core.http.HttpClient.

Pour instancier un client, ajoutez le code suivant à la méthode main :

// You can get your connection string from your resource in the Azure portal.
String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";

EmailClient emailClient = new EmailClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Par souci de simplicité, ce guide de démarrage rapide utilise des chaînes de connexion, mais, dans des environnements de production, nous recommandons l’utilisation de principaux de service.

Sérialiser MessageId à l’aide de EmailClient pour Java

Utilisez le SDK e-mail Azure Communication Services pour Java. Ajoutez la dépendance suivante à votre fichier pom.xml :

Créer un e-mail

// Create an email message with both plain text and HTML content
EmailMessage message = new EmailMessage()
        .setSenderAddress(senderAddress)
        .setToRecipients(recipientAddress)
        .setSubject("Test email from Java Sample")
        .setBodyPlainText("This is plaintext body of test email.")
        .setBodyHtml("<html><h1>This is the html body of test email.</h1></html>");

Envoyer un e-mail et capturer l’ID d’opération

// STEP 1: Send the email and get the initial poller
// This starts the email send operation and returns a poller to monitor progress
SyncPoller<EmailSendResult, EmailSendResult> poller = client.beginSend(message);

// Poll once to get the initial response and extract the operation ID
PollResponse<EmailSendResult> response = poller.poll();
String operationId = response.getValue().getId();
System.out.printf("Sent email send request from first poller (operation id: %s)\n", operationId);

operationId il s’agit de l’identificateur de clé qui vous permet de réalimenter le polleur ultérieurement. Dans les applications réelles, vous stockez généralement cet ID dans une base de données pour référence ultérieure.

Réalimenter le polleur à l’aide de l’ID d’opération

// STEP 2: Demonstrate rehydration using the operation ID
// In a real scenario, you might store this operationId in a database
// and retrieve it later to continue monitoring the operation
System.out.print("Started polling from second poller\n");

// REHYDRATION: Create a new poller using the existing operationId
// This is the key concept - you can recreate a poller from just the operationId
SyncPoller<EmailSendResult, EmailSendResult> poller2 = client.beginSend(operationId);

Interroger l’achèvement et obtenir les résultats

// Wait for the email operation to complete using the rehydrated poller
PollResponse<EmailSendResult> response2 = poller2.waitForCompletion();

// Display the final result
System.out.printf("Successfully sent the email (operation id: %s)\n", poller2.getFinalResult().getId());

Exemple de code

Vous pouvez télécharger l’exemple d’application illustrant cette action à partir de GitHub Azure Samples Envoyer un e-mail Poller de réhydratation pour Java.

Remise d’e-mails

Pour résoudre les problèmes liés à la remise d’e-mails, vous pouvez obtenir l’état de la remise de l’e-mail pour capturer les détails de la remise.

Important

Le résultat de réussite renvoyé par l’interrogation du statut de l’opération d’envoi valide uniquement le fait que l’e-mail est envoyé pour livraison. Pour obtenir plus d'informations sur l'état de la remise du côté du destinataire, consultez comment gérer les événements de messagerie.

Limitation d’email

Si votre application est suspendue, cela peut être dû à la limitation de l’envoi d’e-mails. Vous pouvez gérer la limitation des e-mails en journalisant ou en implémentant une stratégie personnalisée.

Note

Ce bac à sable est destiné à aider les développeurs à créer l’application. Vous pouvez demander progressivement d’augmenter le volume d’envoi une fois que l’application est prête à démarrer. Envoyez une demande de support pour déclencher votre limite d’envoi souhaitée si vous avez besoin d’envoyer un volume de messages dépassant les limites de débit.

Nettoyer les ressources Azure Communication Service

Si vous voulez nettoyer et supprimer un abonnement Communication Services, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées. Apprenez-en davantage sur le nettoyage des ressources.

Étapes suivantes

  • Last updated on