Guida introduttiva: Come inviare un messaggio di posta elettronica con Servizi di comunicazione di Azure

Nota

Condividere le proprie opinioni e i feedback su Servizi di comunicazione di Azure con Microsoft eseguendo questo breve sondaggio.

Questa guida introduttiva spiega come inviare messaggi di posta elettronica usando gli SDK di Email.

Per iniziare a usare Servizi di comunicazione di Azure, usare la funzione Prova posta elettronica per inviare messaggi di posta elettronica di Servizi di comunicazione.

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 attiva connessa al dominio della posta elettronica. 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.

Inviare un messaggio di posta elettronica tramite la funzione Prova posta elettronica

Prova posta elettronica consente di iniziare a inviare messaggi di posta elettronica ai destinatari desiderati tramite Servizi di comunicazione di Azure, nonché di verificare la configurazione dell'applicazione per l'invio di messaggi di posta elettronica. Consente anche di iniziare subito lo sviluppo di notifiche tramite posta elettronica con il frammento di codice nel linguaggio preferito.

Per inviare un messaggio a un destinatario e per specificare l'oggetto e il corpo del messaggio,

1. Nella pagina di panoramica di una risorsa di Servizi di comunicazione di Azure sottoposta a provisioning selezionare Posta elettronica e quindi fare clic su Prova posta elettronica nel pannello di spostamento a sinistra.

   

2. Selezionare uno dei domini verificati dall'elenco a discesa.

   

3. Comporre il messaggio di posta elettronica da inviare

   • Immettere l’indirizzo di posta elettronica del destinatario
   • Immettere l'oggetto
   • Scrivere il corpo del messaggio di posta elettronica

   

4. Fare clic su Invia

   

5. Messaggio di posta elettronica inviato.

   

6. A questo punto è anche possibile copiare il frammento di codice di esempio per inviare un messaggio di posta elettronica da usare nel progetto di esempio per l’invio di notifiche.

   • Selezionare la lingua desiderata

   • Fare clic su Inserisci connessione

   • Fare clic su Copia

     

7. Il frammento di codice di posta elettronica è ora pronto per essere usato nel progetto di notifica.

Per iniziare a usare Servizi di comunicazione di Azure, usare l'estensione di comunicazione dell'interfaccia della riga di comando di Azure per inviare messaggi di posta elettronica.

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

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
• Una risorsa di posta elettronica di Servizi di comunicazione di Azure creata e munita di un dominio sottoposto a provisioning. Introduzione alla creazione di una risorsa di comunicazione tramite posta elettronica.
• Una risorsa di Servizi di comunicazione di Azure attiva connessa al dominio di posta elettronica e relativa stringa di connessione. Per iniziare, connettere una risorsa di comunicazione tramite posta elettronica con una risorsa di Servizi di comunicazione diAzure.
• La versione più recente dell'interfaccia della riga di comando di Azure.

Controllo dei prerequisiti

• In un terminale o in una finestra di comando eseguire il comando az --version per verificare che l'interfaccia della riga di comando di Azure e l'estensione di comunicazione siano installate.
• Per visualizzare i domini verificati con la risorsa di Servizi di comunicazione tramite posta elettronica, accedere al portale di Azure. Individuare la risorsa di posta elettronica di Servizi di comunicazione e aprire la scheda Provisioning dei domini nel riquadro di spostamento sinistro.

Configurazione

Aggiungere l'estensione

Aggiungere l'estensione Servizi di comunicazione di Azure per l'interfaccia della riga di comando di Azure usando il comando az extension.

az extension add --name communication

Accedere all'interfaccia della riga di comando di Azure

È necessario accedere all'interfaccia della riga di comando di Azure. È possibile accedere eseguendo il comando az login dal terminale e specificando le credenziali.

Archiviare la stringa di connessione in una variabile di ambiente

È possibile configurare la variabile di ambiente AZURE_COMMUNICATION_CONNECTION_STRING per usare le operazioni principali dell'interfaccia della riga di comando di Azure senza dover usare --connection_string per passare la stringa di connessione. Per configurare una variabile di ambiente, aprire una finestra della console e selezionare il sistema operativo dalle schede seguenti. Sostituire <connectionString> con la stringa di connessione effettiva.

Nota

Non archiviare la stringa di connessione come variabile di ambiente non crittografata per gli ambienti di produzione. Questa operazione deve essere effettuata solo per i test. Per gli ambienti di produzione è necessario generare nuove stringhe di connessione. È consigliabile crittografare le stringhe di connessione e modificarle regolarmente.

Windows

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Dopo l'aggiunta della variabile di ambiente potrebbe essere necessario riavviare eventuali programmi in esecuzione che necessitano di leggere la variabile di ambiente, inclusa la finestra della console. Se ad esempio si usa Visual Studio come editor, riavviare Visual Studio prima di eseguire l'esempio.

macOS

Modificare .zshrc e aggiungere la variabile di ambiente:

export AZURE_COMMUNICATION_CONNECTION_STRING="<connectionString>"

Dopo avere aggiunto la variabile di ambiente, eseguire source ~/.zshrc dalla finestra della console per rendere effettive le modifiche. Se la variabile di ambiente è stata creata con l'IDE aperto, per accedervi potrebbe essere necessario chiudere e riaprire l'editor, l'IDE o la shell.

Linux

Modificare .bash_profile e aggiungere la variabile di ambiente:

export AZURE_COMMUNICATION_CONNECTION_STRING="<connectionString>"

Dopo avere aggiunto la variabile di ambiente, eseguire source ~/.bash_profile dalla finestra della console per rendere effettive le modifiche. Se la variabile di ambiente è stata creata con l'IDE aperto, per accedervi potrebbe essere necessario chiudere e riaprire l'editor, l'IDE o la shell.

Invio di un messaggio di posta elettronica

az communication email send
	--connection-string "yourConnectionString"
	--sender "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>"
	--to "<emailalias@emaildomain.com>"
	--subject "Welcome to Azure Communication Services Email" --text "This email message is sent from Azure Communication Services Email using Azure CLI." 

Effettuare queste sostituzioni nel codice:

• Sostituire <yourConnectionString> con la stringa di connessione.
• Sostituire <emailalias@emaildomain.com> con l'indirizzo di posta elettronica a cui inviare un messaggio.
• Sostituire <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> con l'indirizzo del mittente del dominio verificato.

Il comando precedente esegue anche un polling sull'ID messaggio e restituisce lo stato di recapito della posta elettronica. Lo stato può essere uno dei seguenti:

Nome dello 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.

Parametri facoltativi

I parametri facoltativi seguenti sono disponibili nell'interfaccia della riga di comando di Azure.

• --html può essere usato invece di --text per il corpo della posta elettronica in formato html.

• --importance imposta il tipo di priorità del messaggio di posta elettronica. I valori validi sono Alta, Normale e Bassa. L'impostazione predefinita è Normale.

• --to imposta l'elenco dei destinatari della posta elettronica.

• --cc imposta gli indirizzi di posta elettronica per la copia per conoscenza.

• --bcc imposta gli indirizzi di posta elettronica per la copia per conoscenza nascosta.

• --reply-to imposta l’indirizzo di posta elettronica di risposta.

• --disable-tracking indica se il rilevamento dell'engagement degli utenti deve essere disabilitato per la richiesta.

• --attachments imposta l'elenco degli allegati di posta elettronica.

• --attachment-types imposta l'elenco dei tipi di allegati di posta elettronica, nello stesso ordine degli allegati.

È anche possibile usare un elenco di destinatari con --cc e --bcc simile a --to. Deve essere presente almeno un destinatario in --to o --cc o --bcc.

Per iniziare a usare Servizi di comunicazione di Azure, usare la libreria client di Posta elettronica di Servizi di comunicazione di Azure per C# per l’invio di 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:

Stringa di connessione

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

Microsoft Entra ID

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

AzureKeyCredential

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

Nota

È consigliabile usare il polling manuale (Inviare un messaggio email con polling dello stato asincrono) per inviare messaggi email.

Inviare un messaggio email con polling dello stato asincrono

Inviare un messaggio di posta elettronica di base

Creare il messaggio di posta elettronica

Per inviare un messaggio di posta elettronica, è necessario:

• Specificare l'oggetto e il corpo del messaggio di posta elettronica.
• Specificare l'indirizzo del mittente. Creare il messaggio di posta elettronica con le informazioni del mittente ottenute dall'indirizzo MailFrom proveniente dal dominio verificato.
• Specificare l'indirizzo del destinatario.
• Chiamare il metodo SendAsync. Aggiungere questo codice alla fine del metodo Main in Program.cs:

Sostituire con i dettagli del dominio e modificare il contenuto e i dettagli del destinatario in base alle esigenze

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

Inviare e ottenere lo stato di invio tramite 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.

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

Inviare un messaggio email con polling dello stato sincrono

Inviare un messaggio di posta elettronica di base

Creare il messaggio di posta elettronica

Per inviare un messaggio di posta elettronica, è necessario:

• Specificare l'oggetto e il corpo del messaggio di posta elettronica.
• Specificare l'indirizzo del mittente. Creare il messaggio di posta elettronica con le informazioni del mittente ottenute dall'indirizzo MailFrom proveniente dal dominio verificato.
• Specificare l'indirizzo del destinatario.
• Chiamare il metodo SendAsync. Aggiungere questo codice alla fine del metodo Main in Program.cs:

Sostituire con i dettagli del dominio e modificare il contenuto e i dettagli del destinatario in base alle esigenze

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

Inviare e ottenere lo stato di invio tramite posta elettronica

Per inviare un messaggio di posta elettronica, è necessario:

• Chiamare il metodo SendAsync che invia la richiesta di posta elettronica come operazione asincrona. Usare Azure.WaitUntil.Completed se il metodo deve attendere il completamento dell'operazione a esecuzione prolungata nel servizio. Usare Azure.WaitUntil.Started se il metodo deve restituire un risultato dopo l'avvio dell'operazione.
• Il metodo SendAsync restituisce EmailSendOperation che restituisce "Succeeded EmailSendStatus se il messaggio di posta elettronica è in uscita, generando un'eccezione in caso contrario. Aggiungere questo codice alla fine del metodo Main in Program.cs:

try
{
    Console.WriteLine("Sending email...");
    EmailSendOperation emailSendOperation = await emailClient.SendAsync(
        Azure.WaitUntil.Completed,
        sender,
        recipient,
        subject,
        htmlContent);
    EmailSendResult statusMonitor = emailSendOperation.Value;

    Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");

    /// 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}");
}
catch (RequestFailedException ex)
{
    /// OperationID is contained in the exception message and can be used for troubleshooting purposes
    Console.WriteLine($"Email send operation failed with error code: {ex.ErrorCode}, message: {ex.Message}");
}

Ottenere lo stato di recapito di un messaggio di posta elettronica

EmailSendOperation restituisce solo lo stato dell'operazione di invio di posta elettronica. Per ottenere lo stato effettivo di recapito della posta elettronica, è possibile abbonarsi all'evento "EmailDeliveryReportReceived" che viene generato al termine del recapito della posta elettronica. L'evento restituisce lo stato di recapito seguente:

• Recapitato.
• non riuscito.
• In quarantena.

Per informazioni dettagliate, vedere Gestire gli eventi della posta elettronica.

È anche possibile abbonarsi ai log operativi della posta elettronica che forniscono informazioni relative alle metriche di recapito per i messaggi inviati dal servizio di posta elettronica.

• Log operativi di invio di messaggi di posta elettronica: forniscono informazioni dettagliate relative alle richieste di messaggi di posta elettronica inviate dal servizio di posta elettronica.
• Log operativi di aggiornamento dello stato della posta elettronica: forniscono aggiornamenti sullo stato di recapito, a livello di messaggio e destinatario, correlato alle richieste di messaggi di posta elettronica inviate dal servizio di posta elettronica.

Accedere ai log per i Servizi di comunicazione tramite posta elettronica.

Eseguire il codice

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

Per iniziare a usare Servizi di comunicazione di Azure, usare la libreria client di Posta elettronica di Servizi di comunicazione per JS 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 Posta elettronica di Servizi di comunicazione di Azure per JavaScript.

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 uno dei contenuti 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.
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).
EmailSendStatus	Questa classe rappresenta il set di stati di un'operazione di invio di posta elettronica.

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

Nome dello stato	Descrizione
isStarted	Restituisce true se l'operazione di invio di posta elettronica è in corso ed è in corso l'elaborazione.
isCompleted	Restituisce true se l'operazione di invio tramite posta elettronica è stata completata senza errori e il messaggio di posta elettronica è in uscita e pronto 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
result	Proprietà presente se l'operazione di invio tramite posta elettronica è stata completata.
Errore	Proprietà presente se l'operazione di invio tramite 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

• Node.js (~14).
• Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente.
• Una risorsa di posta elettronica di Servizi di comunicazione di Azure creata e munita di un dominio sottoposto a provisioning. Introduzione alla creazione di una risorsa di comunicazione tramite posta elettronica.
• Una risorsa di Servizi di comunicazione di Azure attiva connessa al dominio di posta elettronica e relativa stringa di connessione. Per iniziare, connettere una risorsa di comunicazione tramite posta elettronica con una risorsa di Servizi di comunicazione diAzure.

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 un terminale o una finestra di comando eseguire node --version per verificare che Node.js sia installato.
• Per visualizzare i domini verificati con la risorsa Servizi di comunicazione di posta elettronica, accedere al portale di Azure, individuare la risorsa Servizi di comunicazione tramite posta elettronica e aprire la scheda Provisioning dei domini dal riquadro di spostamento sinistro.

Configurare l'ambiente dell'applicazione

Creare una nuova applicazione Node.js

Aprire prima di tutto il terminale o la finestra di comando per creare una nuova directory per l'app e passare a tale directory.

mkdir email-quickstart && cd email-quickstart

Eseguire npm init -y per creare un file package.json con le impostazioni predefinite.

npm init -y

Usare un editor di testo per creare un file denominato send-sms.js nella directory radice del progetto. Modificare la proprietà "main" in package.json in "send-email.js". La sezione segue mostra come aggiungere il codice sorgente indicato in questa guida introduttiva al file appena creato.

Installare il pacchetto

Usare il comando npm install per installare la libreria client di Posta elettronica di Servizi di comunicazione di Azure per JavaScript.

npm install @azure/communication-email --save

L'opzione --save elenca la libreria come dipendenza nel file package.json.

Creare il client di posta elettronica con autenticazione

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

Stringa di connessione

Importare EmailClient dalla libreria client e crearne un'istanza 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. Usare il comando npm install per installare il pacchetto dotenv. Informazioni su come gestire la stringa di connessione della risorsa.

npm install dotenv

Aggiungere il codice seguente al file send-email.js:

const { EmailClient } = require("@azure/communication-email");
require("dotenv").config();

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];
const emailClient = new EmailClient(connectionString);

Microsoft Entra ID

È anche possibile eseguire l'autenticazione con Microsoft Entra ID usando la libreria delle identità di Azure. Per usare il provider DefaultAzureCredential nel frammento di codice seguente o altri provider di credenziali forniti con Azure SDK, installare il pacchetto @azure/identity:

npm install @azure/identity

Il pacchetto @azure/identity fornisce vari tipi di credenziali che l'applicazione può usare per l'autenticazione. README per @azure/identity fornisce altri dettagli ed esempi per iniziare. Sono necessarie le variabili di ambiente AZURE_CLIENT_SECRET, AZURE_CLIENT_ID e AZURE_TENANT_ID per creare un oggetto DefaultAzureCredential.

import { DefaultAzureCredential } from "@azure/identity";
import { EmailClient } from "@azure/communication-email";

const endpoint = "https://<resource-name>.communication.azure.com";
let credential = new DefaultAzureCredential();

const emailClient = new EmailClient(endpoint, credential);

AzureKeyCredential

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.

const { EmailClient, KnownEmailSendStatus } = require("@azure/communication-email");
const { AzureKeyCredential } = require("@azure/core-auth");
require("dotenv").config();

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

const emailClient = new EmailClient(endpoint, key);

Per semplicità, questa guida introduttiva usa stringhe di connessione, ma negli ambienti di produzione è consigliabile usare le entità servizio.

Inviare un messaggio di posta elettronica di base

Invio di un messaggio di posta elettronica

Per inviare un messaggio di posta elettronica, chiamare la funzione beginSend da EmailClient. Questo metodo restituisce un poller che controlla lo stato dell'operazione e recupera il risultato al termine dell'operazione.

async function main() {
  const POLLER_WAIT_TIME = 10
  try {
    const message = {
      senderAddress: "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>",
      content: {
        subject: "Welcome to Azure Communication Services Email",
        plainText: "This email message is sent from Azure Communication Services Email using the JavaScript SDK.",
      },
      recipients: {
        to: [
          {
            address: "<emailalias@emaildomain.com>",
            displayName: "Customer Name",
          },
        ],
      },
    };

    const poller = await emailClient.beginSend(message);

    if (!poller.getOperationState().isStarted) {
      throw "Poller was not started."
    }

    let timeElapsed = 0;
    while(!poller.isDone()) {
      poller.poll();
      console.log("Email send polling in progress");

      await new Promise(resolve => setTimeout(resolve, POLLER_WAIT_TIME * 1000));
      timeElapsed += 10;

      if(timeElapsed > 18 * POLLER_WAIT_TIME) {
        throw "Polling timed out.";
      }
    }

    if(poller.getResult().status === KnownEmailSendStatus.Succeeded) {
      console.log(`Successfully sent the email (operation id: ${poller.getResult().id})`);
    }
    else {
      throw poller.getResult().error;
    }
  } catch (e) {
    console.log(e);
  }
}

main();

Effettuare queste sostituzioni nel codice:

• Sostituire <emailalias@emaildomain.com> con l'indirizzo di posta elettronica a cui inviare un messaggio.
• Sostituire <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> con l'indirizzo MailFrom del dominio verificato.

Eseguire il codice

usare il comando node per eseguire il codice aggiunto al file send-email.js.

node ./send-email.js

Codice di esempio

È possibile scaricare l'app di esempio da GitHub

Per iniziare a usare Servizi di comunicazione di Azure, usare l’SDK di Posta elettronica di Servizi di comunicazione di Azure per Java.

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à dell’SDK di Posta elettronica di Servizi di comunicazione di Azure per Python.

Nome	Descrizione
EmailAddress	Questa classe contiene un indirizzo di posta elettronica e un'opzione per un nome visualizzato.
EmailAttachment	Questa interfaccia crea un allegato di posta elettronica accettando un ID univoco, una stringa di tipo MIME dell'allegato di posta elettronica, una stringa di byte di contenuto e un ID contenuto facoltativo per definirlo 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.
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.
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).
EmailSendStatus	Questa classe rappresenta il set di stati di un'operazione di invio di posta elettronica.

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

Nome dello stato	Descrizione
NOT_STARTED	Questo stato non viene attualmente inviato dal servizio.
IN_PROGRESS	L'operazione di invio di posta elettronica è attualmente in corso ed è in corso l'elaborazione.
SUCCESSFULLY_COMPLETED	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
FAILED	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.
• Java Development Kit (JDK) versione 8 o successiva.
• Apache Maven.
• Una risorsa di Servizi di comunicazione distribuita e una stringa di connessione. Per informazioni dettagliate vedere Creare una risorsa di Servizi di comunicazione di Azure.
• Creare una risorsa di Servizi di comunicazione tramite posta elettronica di Azure per iniziare a inviare messaggi di posta elettronica.
• Un'identità gestita di configurazione per un ambiente di sviluppo, vedere Autorizzare l'accesso con un’identità gestita.

Le procedure illustrate in questa guida di avvio rapido 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, vedere Aggiungere domini verificati personalizzati al Servizio di comunicazione tramite posta elettronica.

Controllo dei prerequisiti

• In una finestra del terminale o di comando eseguire mvn -v per controllare che Maven sia installato.
• Per visualizzare i domini verificati con la risorsa di Servizi di comunicazione tramite posta elettronica, accedere al portale di Azure. Individuare la risorsa di posta elettronica di Servizi di comunicazione e aprire la scheda Provisioning dei domini nel riquadro di spostamento sinistro.

Configurare l'ambiente dell'applicazione

Per configurare un ambiente per l'invio di messaggi, seguire la procedura descritta nelle sezioni seguenti.

Creare una nuova applicazione Java

Aprire la finestra del terminale o di comando e passare alla directory in cui creare l'applicazione Java. Eseguire il comando seguente per generare il progetto Java dal modello 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'obiettivo generate crea una directory con lo stesso nome del valore artifactId. In questa directory, la directory src/main/java contiene il codice sorgente del progetto, la directory src/test/java contiene l'origine di test e il file pom.xml è il modello a oggetti del progetto (POM).

Installare il pacchetto

Aprire il file pom.xml nell'editor di testo. Aggiungere l'elemento di dipendenza seguente al gruppo di dipendenze.

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

Configurare il framework dell'app

Aprire /src/main/java/com/communication/quickstart/App.java in un editor di testo, aggiungere le direttive import e rimuovere l'istruzione 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.*;

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

Creare il client di posta elettronica con autenticazione

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

Stringa di connessione

Per autenticare un client, creare un'istanza di EmailClient con la stringa di connessione. Informazioni su come gestire la stringa di connessione della risorsa . È inoltre possibile inizializzare il client con qualsiasi client HTTP personalizzato che implementi l'interfaccia com.azure.core.http.HttpClient.

Per creare un'istanza di un client sincrono, aggiungere il codice seguente al metodo 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();

Per creare un'istanza di un client asincrono, aggiungere il codice seguente al metodo 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>";

EmailAsyncClient emailClient = new EmailClientBuilder()
    .connectionString(connectionString)
    .buildAsyncClient();

Microsoft Entra ID

È necessario passare un oggetto DefaultAzureCredential a EmailClientBuilder tramite il metodo credential(). È anche necessario impostare un endpoint tramite il metodo endpoint().

Sono necessarie le variabili di ambiente AZURE_CLIENT_SECRET, AZURE_CLIENT_ID e AZURE_TENANT_ID per creare un oggetto DefaultAzureCredential.

Per creare un'istanza di un client sincrono, aggiungere il codice seguente al metodo main:

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<resource-name>.communication.azure.com/";
EmailClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Per creare un'istanza di un client asincrono, aggiungere il codice seguente al metodo main:

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<resource-name>.communication.azure.com/";
EmailAsyncClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildAsyncClient();

AzureKeyCredential

È anche possibile creare e autenticare i client di posta elettronica usando l'endpoint e le credenziali della chiave di Azure acquisite da una risorsa di Servizi di comunicazione di Azure nel portale di Azure.

Per creare un'istanza di un client sincrono, aggiungere il codice seguente al metodo main:

String endpoint = "https://<resource-name>.communication.azure.com";
AzureKeyCredential azureKeyCredential = new AzureKeyCredential("<access-key>");
EmailClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(azureKeyCredential)
    .buildClient();

Per creare un'istanza di un client asincrono, aggiungere il codice seguente al metodo main:

String endpoint = "https://<resource-name>.communication.azure.com";
AzureKeyCredential azureKeyCredential = new AzureKeyCredential("<access-key>");
EmailClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(azureKeyCredential)
    .buildClient();

Per semplicità, questa guida introduttiva usa stringhe di connessione, ma negli ambienti di produzione è consigliabile usare le entità servizio.

Inviare un messaggio di posta elettronica di base

È possibile creare un messaggio di posta elettronica usando l'oggetto EmailMessage nell’SDK.

EmailMessage message = new EmailMessage()
    .setSenderAddress("<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>")
    .setToRecipients("<emailalias@emaildomain.com>")
    .setSubject("Welcome to Azure Communication Services Email")
    .setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.");

Effettuare queste sostituzioni nel codice:

• Sostituire <emailalias@emaildomain.com> con l'indirizzo di posta elettronica a cui inviare un messaggio.
• Sostituire <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> con l'indirizzo MailFrom del dominio verificato.

Per inviare il messaggio di posta elettronica, chiamare la funzione beginSend da EmailClient.

Client di sincrono

La chiamata di beginSend nel client sincrono restituisce un oggetto SyncPoller, che può essere usato per controllare lo stato dell'operazione e recuperare il risultato al termine dell'operazione. Si noti che la richiesta iniziale di invio di un messaggio di posta elettronica verrà inviata non appena viene chiamato il metodo beginSend. L'invio di un messaggio di posta elettronica è un'operazione a esecuzione prolungata. È importante notare che il metodo getFinalResult() nel poller è un'operazione che blocca il terminale fino a quando non raggiunge un determinato stato (SUCCESSFULLY_COMPLETED o FAILED). Il metodo consigliato consiste nell'eseguire il polling manuale a un intervallo appropriato in base alle esigenze dell'applicazione, come illustrato nell'esempio seguente.

try
{
    SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null); // This will send out the initial request to send an email

    PollResponse<EmailSendResult> pollResponse = null;

    Duration timeElapsed = Duration.ofSeconds(0);
    Duration POLLER_WAIT_TIME = Duration.ofSeconds(10);

    // Polling is done manually to avoid blocking the application in case of an error
    while (pollResponse == null
            || pollResponse.getStatus() == LongRunningOperationStatus.NOT_STARTED
            || pollResponse.getStatus() == LongRunningOperationStatus.IN_PROGRESS)
    {
        pollResponse = poller.poll();
        System.out.println("Email send poller status: " + pollResponse.getStatus());

        Thread.sleep(POLLER_WAIT_TIME.toMillis());
        timeElapsed = timeElapsed.plus(POLLER_WAIT_TIME);

        if (timeElapsed.compareTo(POLLER_WAIT_TIME.multipliedBy(18)) >= 0)
        {
            throw new RuntimeException("Polling timed out.");
        }
    }

    if (poller.getFinalResult().getStatus() == EmailSendStatus.SUCCEEDED)
    {
        System.out.printf("Successfully sent the email (operation id: %s)", poller.getFinalResult().getId());
    }
    else
    {
        throw new RuntimeException(poller.getFinalResult().getError().getMessage());
    }
}
catch (Exception exception)
{
    System.out.println(exception.getMessage());
}

Client asincrono

La chiamata di beginSend nel client asincrono restituisce un oggetto PollerFlux a cui è possibile abbonarsi. I callback definiti nel metodo subscribe verranno attivati al termine dell'operazione di invio del messaggio di posta elettronica. Si noti che la richiesta iniziale di invio di un messaggio di posta elettronica non verrà inviata fino a quando non viene configurato un sottoscrittore.

PollerFlux<EmailSendResult, EmailSendResult> poller = emailAsyncClient.beginSend(emailMessage);
// The initial request is sent out as soon as we subscribe the to PollerFlux object
poller.subscribe(
        response -> {
            if (response.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
                System.out.printf("Successfully sent the email (operation id: %s)", response.getValue().getId());
            }
            else {
                System.out.println("Email send status: " + response.getStatus());
            }
        },
        error -> {
            System.out.println("Error occurred while sending email: " + error.getMessage());
        }
);

Eseguire il codice

1. Passare alla directory che contiene il file pom.xml e compilare il progetto usando il comando mvn.

   mvn compile
   

2. Compilare il pacchetto.

   mvn package
   

3. Eseguire il comando mvn seguente per eseguire l'app.

   mvn exec:java -D"exec.mainClass"="com.communication.quickstart.App" -D"exec.cleanupDaemonThreads"="false"
   

Codice di esempio

È possibile scaricare l'app di esempio da GitHub

Per iniziare a usare Servizi di comunicazione di Azure, usare l’SDK di Posta elettronica di Servizi di comunicazione per Python per inviare i 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

Il modello di messaggio JSON e l’oggetto risposta illustrano alcune delle principali funzionalità dell’SDK di Posta elettronica di Servizi di comunicazione di Azure per Python.

message = {
    "content": {
        "subject": "str",  # Subject of the email message. Required.
        "html": "str",  # Optional. Html version of the email message.
        "plainText": "str"  # Optional. Plain text version of the email
            message.
    },
    "recipients": {
        "to": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ],
        "bcc": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ],
        "cc": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ]
    },
    "senderAddress": "str",  # Sender email address from a verified domain. Required.
    "attachments": [
        {
            "contentInBase64": "str",  # Base64 encoded contents of the attachment. Required.
            "contentType": "str",  # MIME type of the content being attached. Required.
            "name": "str"  # Name of the attachment. Required.
        }
    ],
    "userEngagementTrackingDisabled": bool,  # Optional. Indicates whether user engagement tracking should be disabled for this request if the resource-level user engagement tracking setting was already enabled in the control plane.
    "headers": {
        "str": "str"  # Optional. Custom email headers to be passed.
    },
    "replyTo": [
        {
            "address": "str",  # Email address. Required.
            "displayName": "str"  # Optional. Email display name.
        }
    ]
}

response = {
    "id": "str",  # The unique id of the operation. Uses a UUID. Required.
    "status": "str",  # Status of operation. Required. Known values are:
        "NotStarted", "Running", "Succeeded", and "Failed".
    "error": {
        "additionalInfo": [
            {
                "info": {},  # Optional. The additional info.
                "type": "str"  # Optional. The additional info type.
            }
        ],
        "code": "str",  # Optional. The error code.
        "details": [
            ...
        ],
        "message": "str",  # Optional. The error message.
        "target": "str"  # Optional. The error target.
    }
}

I valori response.status sono illustrati più avanti nella tabella seguente.

Nome dello stato	Descrizione
InProgress	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.
• Python 3.7+.
• Una risorsa di posta elettronica di Servizi di comunicazione di Azure creata e munita di un dominio sottoposto a provisioning. Introduzione alla creazione di una risorsa di comunicazione tramite posta elettronica.
• Una risorsa di Servizi di comunicazione di Azure attiva connessa al dominio di posta elettronica e relativa stringa di connessione. Per iniziare, connettere una risorsa di comunicazione tramite posta elettronica con una risorsa di Servizi di comunicazione diAzure.

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 python --version per verificare se Python è installato.
• Per visualizzare i domini verificati con la risorsa di Servizi di comunicazione tramite posta elettronica, accedere al portale di Azure. Individuare la risorsa di posta elettronica di Servizi di comunicazione e aprire la scheda Provisioning dei domini nel riquadro di spostamento sinistro.

Configurare l'ambiente dell'applicazione

Per configurare un ambiente per l'invio di messaggi, seguire la procedura descritta nelle sezioni seguenti.

Creare una nuova applicazione Python

1. Aprire la finestra del terminale o di comando. Usare quindi il comando seguente per creare un ambiente virtuale e attivarlo. Questo comando crea una nuova directory per l'app.

   python -m venv email-quickstart
   

2. Passare alla directory radice dell'ambiente virtuale e attivarla usando i comandi seguenti.

   cd email-quickstart
   .\Scripts\activate
   

3. Usare un editor di testo per creare un file denominato send.email.py nella directory radice del progetto e aggiungere la struttura per il programma, inclusa la gestione delle eccezioni di base.

   import os
   from azure.communication.email import EmailClient
   
   try:
       # Quickstart code goes here.
   except Exception as ex:
       print('Exception:')
       print(ex)
   

Nelle sezioni seguenti, tutto il codice sorgente usato in questa guida introduttiva verrà aggiunto al file send-email.py appena creato.

Installare il pacchetto

Sempre all’interno della directory dell'applicazione, installare il pacchetto dell’SDK di Posta elettronica di Servizi di comunicazione di Azure per Python usando il comando seguente.

pip install azure-communication-email

Creare il client di posta elettronica con autenticazione

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

Stringa di connessione

Creare un'istanza di EmailClient con la stringa di connessione. Informazioni su come gestire la stringa di connessione della risorsa .

# Create the EmailClient object that you use to send Email messages.
email_client = EmailClient.from_connection_string(<connection_string>)

Microsoft Entra ID

È anche possibile usare l'autenticazione di Active Directory con DefaultAzureCredential.

from azure.communication.email import EmailClient
from azure.identity import DefaultAzureCredential

# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
endpoint = "https://<resource-name>.communication.azure.com"
email_client = EmailClient(endpoint, DefaultAzureCredential())

AzureKeyCredential

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.

from azure.communication.email import EmailClient
from azure.core.credentials import AzureKeyCredential

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

email_client = EmailClient(endpoint, key);

Per semplicità, questa guida introduttiva usa stringhe di connessione, ma negli ambienti di produzione è consigliabile usare le entità servizio.

Inviare un messaggio di posta elettronica di base

Invio di un messaggio di posta elettronica

Per inviare un messaggio di posta elettronica, è necessario:

• Creare il messaggio con i valori seguenti:
  • senderAddress: indirizzo di posta elettronica del mittente valido, disponibile nel campo MailFrom del riquadro di panoramica del dominio collegato alla risorsa di Servizi di comunicazione tramite posta elettronica.
  • recipients: oggetto con un elenco di destinatari di posta elettronica e, facoltativamente, elenchi di destinatari CC e CCN.
  • content: oggetto contenente l'oggetto e, facoltativamente, il testo non crittografato o il contenuto HTML di un messaggio di posta elettronica.
• Chiamare il metodo begin_send, che restituisce il risultato dell'operazione.

message = {
    "content": {
        "subject": "This is the subject",
        "plainText": "This is the body",
        "html": "<html><h1>This is the body</h1></html>"
    },
    "recipients": {
        "to": [
            {
                "address": "<emailalias@emaildomain.com>",
                "displayName": "Customer Name"
            }
        ]
    },
    "senderAddress": "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>"
}

poller = email_client.begin_send(message)
print("Result: " + poller.result())

Effettuare queste sostituzioni nel codice:

• Sostituire <emailalias@emaildomain.com> con l'indirizzo di posta elettronica a cui inviare un messaggio.
• Sostituire <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> con l'indirizzo MailFrom del dominio verificato.

Ottenere lo stato del recapito tramite posta elettronica

È possibile eseguire il polling dello stato del recapito tramite posta elettronica impostando un ciclo sull'oggetto stato dell'operazione restituito dal metodo begin_send di EmailClient:

POLLER_WAIT_TIME = 10

try:
    email_client = EmailClient.from_connection_string(connection_string)

    poller = email_client.begin_send(message);

    time_elapsed = 0
    while not poller.done():
        print("Email send poller status: " + poller.status())

        poller.wait(POLLER_WAIT_TIME)
        time_elapsed += POLLER_WAIT_TIME

        if time_elapsed > 18 * POLLER_WAIT_TIME:
            raise RuntimeError("Polling timed out.")

    if poller.result()["status"] == "Succeeded":
        print(f"Successfully sent the email (operation id: {poller.result()['id']})")
    else:
        raise RuntimeError(str(poller.result()["error"]))

except Exception as ex:
    print(ex)

Eseguire il codice

Eseguire l'applicazione dalla directory dell'applicazione con il comando python.

python send-email.py

Codice di esempio

È possibile scaricare l'app di esempio da GitHub

Prerequisiti

• Un account Azure con una sottoscrizione attiva; in alternativa, creare un account gratuito.

• Una risorsa attiva di Servizi di comunicazione di Azure; in alternativa, creare una risorsa di Servizi di comunicazione.

• Una risorsa di App per la logica di Azure attiva (app per la logica) e un flusso di lavoro oppure creare una nuova risorsa e un nuovo flusso di lavoro per l’app per la logica con il trigger desiderato. Attualmente, il connettore Posta elettronica di Servizi di comunicazione di Azure prevede solo azioni, quindi il flusso di lavoro dell'app per la logica richiede almeno un trigger. È possibile creare una risorsa dell'app per la logica a consumo o standard.

• Risorsa di Posta elettronica di Servizi di comunicazione di Azure con un dominio configurato o un dominio personalizzato.

• Una risorsa di Servizi di comunicazione di Azure connessa a un dominio di posta elettronica di Azure.

Inviare un messaggio e-mail

Per aggiungere un nuovo passaggio al flusso di lavoro tramite il connettore Posta elettronica di Servizi di comunicazione di Azure, seguire questa procedura:

1. Nella finestra di progettazione aprire il flusso di lavoro dell'app per la logica.

   Consumo

   1. Nel passaggio in cui si vuole aggiungere la nuova azione selezionare Nuovo passaggio. In alternativa, per aggiungere la nuova azione tra i passaggi, spostare il puntatore sulla freccia tra tali passaggi, selezionare il segno più (+) e quindi selezionare Aggiungi un'azione.

   2. Nella casella di ricerca Scegliere un'operazione selezionare Premium. Nella casella di ricerca immettere Posta elettronica di Servizi di comunicazione di Azure.

   3. Nell'elenco di azioni selezionare Invia messaggio di posta elettronica.

      

   Standard

   1. Nel passaggio in cui si vuole aggiungere la nuova azione selezionare il segno più (+). In alternativa, per aggiungere la nuova azione tra i passaggi, spostare il puntatore sulla freccia tra tali passaggi, selezionare il segno più (+) e quindi selezionare Aggiungi un'azione.

   2. Nella casella di ricerca Aggiungi un'azione selezionare l’elenco a discesa Runtime e quindi scegliere Premium. Nella casella di ricerca immettere Posta elettronica di Servizi di comunicazione di Azure.

   3. Nell'elenco di azioni selezionare Invia messaggio di posta elettronica.

2. Specificare un nome per la connessione.

3. Immettere la stringa di connessione per la risorsa di Servizi di comunicazione di Azure. Per trovare questa stringa, seguire questa procedura:

   1. Nel portale di Azure aprire la risorsa di Servizi di comunicazione di Azure.

   2. Nel menu della risorsa, selezionare Impostazioni, scegliere Chiavi e copiare la stringa di connessione.

      

4. Al termine, seleziona Crea.

5. Nel campo Da usare l'indirizzo di posta elettronica configurato nei prerequisiti. Immettere i valori nei campi Destinatario, Oggetto e Corpo, ad esempio:

   

6. Salvare il flusso di lavoro. Sulla barra degli strumenti della finestra di progettazione seleziona Salva.

Testare il flusso di lavoro

Avviare manualmente il flusso del lavoro, a seconda del fatto che si disponga o meno di un flusso di lavoro A consumo o Standard:

• A consumo: nella barra degli strumenti della finestra di progettazione selezionare Esegui trigger>Esegui.
• Standard: nel menu del flusso di lavoro selezionare Panoramica. Nella barra degli strumenti selezionare Esegui trigger>Esegui.

Il flusso di lavoro crea un utente, rilascia un token di accesso per tale utente, quindi rimuove ed elimina l'utente. È possibile controllare gli output di queste azioni al termine dell’esecuzione del flusso di lavoro.

Viene generalmente inviato un messaggio di posta elettronica all'indirizzo specificato. È anche possibile usare l'azione Ottieni stato del messaggio di posta elettronica per controllare lo stato dei messaggi di posta elettronica inviati tramite l'azione Invia messaggio di posta elettronica. Per informazioni su altre azioni, vedere la documentazione di riferimento sul connettore Posta elettronica di Servizi di comunicazione di Azure.

Pulire le risorse del flusso di lavoro

Per pulire la risorsa dell'app per la logica, il flusso di lavoro e le risorse correlate, vedere Come pulire le risorse dell'app per la logica a consumo o Come pulire le risorsedell'app per la logica standard.

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

Per pulire e rimuovere una sottoscrizione di Servizi di comunicazione, è possibile eliminare la risorsa o il gruppo di risorse. Se si elimina il gruppo di risorse vengono eliminate anche tutte le altre risorse associate. Altre informazioni sulla pulizia delle risorse.

Passaggi successivi

In questa guida introduttiva si è appreso come inviare messaggi di posta elettronica tramite Servizi di comunicazione di Azure. È anche possibile:

• Acquisire informazioni sui concetti relativi alla posta elettronica.
• Acquisire familiarità con la libreria client di Posta elettronica.
• Acquisire altre informazioni su come inviare un messaggio di chat da Power Automate usando Servizi di comunicazione di Azure.
• Acquisire altre informazioni sul check-in dei token di accesso facendo riferimento a Creare e gestire gli utenti e i token di accesso di Servizi di comunicazione di Azure.