Guida introduttiva: Eseguire manualmente il polling dello stato della posta elettronica durante l'invio di messaggi di posta elettronica

Articolo
10/03/2024

In questa guida introduttiva si apprenderà come eseguire manualmente il polling dello stato della posta elettronica durante l'invio di messaggi di posta elettronica usando gli SDK di posta elettronica.

Per iniziare a usare Servizi di comunicazione di Azure, usare la libreria client di posta elettronica .NET di Servizi di comunicazione per inviare messaggi di posta elettronica.

Suggerimento

Iniziare subito l'esperienza di invio di messaggi di posta elettronica con Servizi di comunicazione di Azure passando direttamente al codice di esempio Invio di messaggi di posta elettronica Basic e Invio di messaggi di posta elettronica Advanced in GitHub.

Informazioni sul modello a oggetti Posta elettronica

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità della libreria client di Posta Elettronica di Servizi di comunicazione di Azure per C#.

Nome	Descrizione
EmailAddress	Questa classe contiene un indirizzo di posta elettronica e un'opzione per un nome visualizzato.
EmailAttachment	Questa classe crea un allegato di posta elettronica accettando un ID univoco, una stringa MIME di tipo allegato di posta elettronica, dati binari per il contenuto e un ID contenuto facoltativo da definire come allegato inline.
EmailClient	Questa classe è necessaria per tutte le funzionalità della posta elettronica. È possibile crearne un'istanza con la stringa di connessione e usarla per inviare messaggi di posta elettronica.
EmailClientOptions	Questa classe può essere aggiunta all'istanza di EmailClient per specificare una versione dell'API come destinazione.
EmailContent	Questa classe contiene l'oggetto e il corpo del messaggio di posta elettronica. È necessario specificare almeno un contenuto in testo normale o formato Html
EmailCustomHeader	Questa classe consente di aggiungere un nome e una coppia di valori per personalizzare un'intestazione. È possibile anche specificare la priorità tramite le intestazioni usando il nome dell’intestazione 'x-priority' o 'x-msmail-priority'
EmailMessage	Questa classe combina il mittente, il contenuto e i destinatari. Facoltativamente, è anche possibile aggiungere intestazioni, allegati e indirizzi di posta elettronica di risposta personalizzati.
EmailRecipients	Questa classe contiene elenchi di oggetti EmailAddress per i destinatari del messaggio di posta elettronica, tra cui gli elenchi facoltativi per i destinatari CC e CCN.
EmailSendOperation	Questa classe rappresenta l'operazione di invio di posta elettronica asincrona e viene restituita dalla chiamata API di invio tramite posta elettronica.
EmailSendResult	Questa classe contiene i risultati dell'operazione di invio tramite posta elettronica. Include un ID operazione, lo stato dell'operazione e l'oggetto dell’errore (se applicabile).

EmailSendResult restituisce lo stato seguente nell'operazione di completamento dell’invio di posta elettronica.

Stato	Descrizione
NotStarted	Questo stato non viene attualmente inviato dal servizio.
In esecuzione	L'operazione di invio di posta elettronica è attualmente in corso ed è in corso l'elaborazione.
Completato	L'operazione di invio tramite posta elettronica è stata completata senza errori e il messaggio di posta elettronica è in uscita per il recapito. È possibile ottenere qualsiasi stato dettagliato relativo al recapito della posta elettronica oltre questa fase tramite Monitoraggio di Azure o Griglia di eventi di Azure. Informazioni su come abbonarsi a eventi di posta elettronica
Non riuscito	L'operazione di invio della posta elettronica non è riuscita e si è verificato un errore. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore.

Prerequisiti

Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
La versione più recente della libreria client .NET Core per il sistema operativo in uso.
Una risorsa di posta elettronica di Servizi di comunicazione di Azure creata e pronta all’uso con un dominio sottoposto a provisioning, vedere Introduzione alla creazione di una risorsa di comunicazione tramite posta elettronica
Una risorsa di Servizi di comunicazione di Azure attiva connessa al dominio della posta elettronica e a una stringa di connessione. Introduzione alla connessione di una risorsa di posta elettronica con una risorsa di comunicazione

L’esecuzione delle procedure illustrate in questa guida introduttiva comportano l'addebito di qualche centesimo (USD) o meno nell'account Azure.

Nota

È anche possibile inviare un messaggio di posta elettronica dal proprio dominio verificato. Aggiungere domini verificati personalizzati a Servizio di comunicazione tramite posta elettronica.

Controllo dei prerequisiti

In una finestra del terminale o di comando eseguire il comando dotnet per verificare se la libreria client .NET è installata.
Per visualizzare i sottodomini associati alla risorsa di Servizio di comunicazione tramite posta elettronica, accedere al portale di Azure, individuare la risorsa di Servizi di comunicazione tramite posta elettronica e aprire la scheda Domini precedenti nel riquadro di spostamento sinistro.

Creare una nuova applicazione C#

In una finestra di una console, ad esempio cmd, PowerShell o Bash, usare il comando dotnet new per creare una nuova app console con il nome EmailQuickstart. Questo comando crea un semplice progetto C# "Hello World" con un singolo file di origine: Program.cs.

dotnet new console -o EmailQuickstart

Passare alla cartella dell'app appena creata e usare il comando dotnet build per compilare l'applicazione.

cd EmailQuickstart
dotnet build

Installare il pacchetto

Sempre all’interno della directory dell'applicazione, installare il pacchetto della libreria client Posta elettronica di Servizi di comunicazione di Azure per .NET usando il comando dotnet add package.

dotnet add package Azure.Communication.Email

Creare il client di posta elettronica con autenticazione

Aprire Program.cs e sostituire il codice esistente con il codice seguente per aggiungere le direttive using per includere lo spazio dei nomi e un punto di partenza per l'esecuzione di Azure.Communication.Email per il programma.


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)
    {

    }
  }
}

Sono disponibili alcune opzioni diverse per l'autenticazione di un client di posta elettronica:

Aprire Program.cs in un editor di testo e sostituire il corpo del metodo Main con il codice per inizializzare un oggetto EmailClient con la stringa di connessione. Il codice seguente recupera la stringa di connessione per la risorsa da una variabile di ambiente denominata COMMUNICATION_SERVICES_CONNECTION_STRING. Informazioni su come gestire la stringa di connessione della risorsa.

// 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);

Per eseguire l'autenticazione con Azure Active Directory, installare il pacchetto della libreria per .NET Azure.Identity usando il comando dotnet add package.

dotnet add package Azure.Identity

Aprire Program.cs in un editor di testo e sostituire il corpo del metodo Main con il codice per inizializzare un oggetto EmailClient con DefaultAzureCredential. Azure Identity SDK legge i valori da tre variabili di ambiente in fase di esecuzione per autenticare l'applicazione. Informazioni su come creare un'applicazione registrata di Azure Active Directory e impostare le variabili di ambiente.

// This code demonstrates how to authenticate to your Communication Service resource using
// DefaultAzureCredential and the environment variables AZURE_CLIENT_ID, AZURE_TENANT_ID,
// and AZURE_CLIENT_SECRET.
string resourceEndpoint = "<ACS_RESOURCE_ENDPOINT>";
EmailClient emailClient = new EmailClient(new Uri(resourceEndpoint), new DefaultAzureCredential());

I client di posta elettronica possono anche essere autenticati usando AzureKeyCredential. Entrambe le classi key e endpoint sono disponibili in “Impostazioni” nel riquadro “Chiavi” della risorsa Servizi di comunicazione.

var key = new AzureKeyCredential("<your-key-credential>");
var endpoint = new Uri("<your-endpoint-uri>");

var emailClient = new EmailClient(endpoint, key);

Invio di messaggi asincroni e polling per lo stato di invio della posta elettronica

Quando si esegue una chiamata a SendAsync con Azure.WaitUntil.Started, il metodo viene restituito dopo l'avvio dell'operazione. Il metodo restituisce l'oggetto EmailSendOperation. È possibile chiamare il metodo UpdateStatusAsync per aggiornare lo stato dell'operazione di invio di messaggi email.

L'oggetto EmailSendOperation restituito contiene un oggetto EmailSendStatus che include:

Lo stato corrente dell'operazione di invio di messaggi email.
Un oggetto di errore con i dettagli dell'errore se lo stato corrente è Operazione non riuscita.


//Replace with your domain and modify the content, recipient details as required
var subject = "Welcome to Azure Communication Service Email APIs.";
var htmlContent = "<html><body><h1>Quick send email test</h1><br/><h4>This email message is sent from Azure Communication Service Email.</h4><p>This mail was sent using .NET SDK!!</p></body></html>";
var sender = "donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net";
var recipient = "emailalias@contoso.com";

/// Send the email message with WaitUntil.Started
EmailSendOperation emailSendOperation = await emailClient.SendAsync(
    Azure.WaitUntil.Started,
    sender,
    recipient,
    subject,
    htmlContent);

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

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

/// Get the OperationId so that it can be used for tracking the message for troubleshooting
string operationId = emailSendOperation.Id;
Console.WriteLine($"Email operation id = {operationId}");

Eseguire l'applicazione dalla directory dell'applicazione con il comando dotnet run.

dotnet run

Codice di esempio

È possibile scaricare l'app di esempio da GitHub

Risoluzione dei problemi

Recapito tramite posta elettronica

Per risolvere i problemi relativi al recapito tramite posta elettronica, è possibile ottenere lo stato del recapito tramite posta elettronica per acquisire i dettagli di recapito.

Importante

Un risultato con positivo restituito dal polling per lo stato dell'operazione di invio conferma solo il fatto che il messaggio di posta elettronica è stato inviato correttamente per il recapito. Per ottenere informazioni aggiuntive sullo stato del recapito al destinatario finale, è necessario fare riferimento a Come gestire gli eventi di posta elettronica.

Limitazione della posta elettronica

Se si nota che l'applicazione si blocchi, è possibile che il problema sia dovuto a una limitazione dell'invio di messaggi di posta elettronica. È possibile gestire il problema registrando o implementando un criterio personalizzato.

Nota

Questa configurazione sandbox consente agli sviluppatori di iniziare a compilare l'applicazione. È possibile richiedere di aumentare progressivamente il volume di invio appena l'applicazione passa allo stato operativo. Inviare una richiesta di supporto per aumentare il limite di invio se si ha la necessità di inviare un volume di messaggi che superano i limiti di frequenza.

Pulire le risorse di Servizi di comunicazione di Azure

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di comunicazione, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate. Altre informazioni sulla pulizia delle risorse.

Passaggi successivi

In questa guida introduttiva si è appreso come eseguire manualmente il polling dello stato durante l'invio di messaggi di posta elettronica tramite Servizi di comunicazione di Azure.

Può essere utile vedere anche gli articoli seguenti:

Informazioni su come inviare messaggi di posta elettronica a più destinatari
Altre informazioni sull'invio di messaggi di posta elettronica con allegati
Acquisire familiarità con la libreria client di posta elettronica

Condividi tramite