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

  • Articolo

In questa guida introduttiva si apprenderà come inviare messaggi di posta elettronica usando gli SDK di Email.

Iniziare a usare Servizi di comunicazione di Azure usando l'estensione di comunicazione dell'interfaccia della riga di comando di Azure per inviare messaggi di Email.

Il completamento di questo avvio rapido comporta un piccolo costo di pochi centesimi di USD o minore nell'account Azure.

Prerequisiti

Controllo dei prerequisiti

  • In un terminale o in una finestra di comando eseguire il az --version comando 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 servizi di comunicazione Email, accedere alla portale di Azure. Individuare la risorsa Email Servizi di comunicazione e aprire la scheda Effettuare il provisioning dei domini dal riquadro di spostamento a sinistra.

Configurazione

Aggiungere l'estensione

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

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 az login comando dal terminale e specificando le credenziali.

Archiviare la stringa di connessione in una variabile di ambiente

È possibile configurare la variabile di ambiente per usare le operazioni delle chiavi dell'interfaccia della AZURE_COMMUNICATION_CONNECTION_STRING 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.

setx AZURE_COMMUNICATION_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. Ad esempio, se si usa Visual Studio come editor, riavviare Visual Studio prima di eseguire l'esempio.

Inviare 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."

Apportare 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 MailFrom del dominio verificato.

Per tenere traccia dello stato del recapito di posta elettronica, è necessario eseguire la messageId risposta.

Parametri facoltativi

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

  • --html può essere usato anziché --text per il corpo della posta elettronica html.

  • --importance imposta il tipo di importanza per il messaggio di posta elettronica. I valori noti sono: alto, normale e basso. Il valore predefinito è normale.

  • --cc imposta gli indirizzi di posta elettronica di copia di carbonio.

  • --bcc imposta gli indirizzi di posta elettronica di copia di carbonio cieco.

  • --reply-to imposta Reply-To indirizzo di posta elettronica.

  • --disable-tracking indica se il rilevamento dell'engagement dell'utente deve essere disabilitato per questa 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 di allegati.

È anche possibile usare un elenco di destinatari con --to, simile a --cc e --bcc.

Ottenere lo stato del recapito tramite posta elettronica

È possibile controllare lo stato del recapito tramite posta elettronica fino a quando lo stato non è OutForDelivery.

az communication email status get --message-id "\<messageId\>"
  • Sostituire "<messageId" con il messageId> dalla risposta della richiesta di invio.
Nome stato Descrizione
NotStarted Questo stato non viene inviato dal servizio in questo momento.
In esecuzione L'operazione di invio di posta elettronica è attualmente in corso e in fase di elaborazione.
Completato L'operazione di invio di posta elettronica è stata completata senza errori e il messaggio di posta elettronica non è disponibile per il recapito. Qualsiasi stato dettagliato sul recapito della posta elettronica oltre questa fase può essere ottenuto tramite Monitoraggio di Azure o tramite Griglia di eventi di Azure. Informazioni su come sottoscrivere eventi di posta elettronica
Non riuscito L'operazione di invio di posta elettronica non ha avuto esito positivo e ha rilevato un errore. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore o dell'annullamento.
Cancellati L'operazione di invio di posta elettronica è stata annullata prima del completamento. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore o dell'annullamento.

Iniziare a usare Servizi di comunicazione di Azure usando la libreria client C# di Servizi di comunicazione Email per inviare messaggi Email.

Suggerimento

Iniziare l'esperienza di invio tramite posta elettronica con Servizi di comunicazione di Azure ignorando direttamente l'Email Basic Email Invio e Advanced Email Invio di codice di esempio in GitHub.

Informazioni sul modello a oggetti Email

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità della libreria client di Servizi di comunicazione di Azure Email 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 di tipo MIME dell'allegato di posta elettronica e i dati binari per il contenuto.
EmailClient Questa classe è necessaria per tutte le funzionalità di 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 la destinazione di una versione API specifica.
EmailContent Questa classe contiene l'oggetto e il corpo del messaggio di posta elettronica. È necessario specificare almeno uno dei contenuti PlainText o Html
EmailCustomHeader Questa classe consente l'aggiunta di un nome e una coppia di valori per un'intestazione personalizzata. Email importanza può essere specificata anche tramite queste intestazioni usando il nome di intestazione 'x-priority' o 'x-msmail-priority'
EmailMessage Questa classe combina il mittente, il contenuto e i destinatari. Anche le intestazioni personalizzate, gli allegati e gli indirizzi di posta elettronica di risposta possono essere aggiunti facoltativamente.
EmailRecipients Questa classe contiene elenchi di oggetti EmailAddress per i destinatari del messaggio di posta elettronica, inclusi gli elenchi facoltativi per & i destinatari cccc.
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 di posta elettronica. Ha un ID operazione, lo stato dell'operazione e l'oggetto errore (quando applicabile).

EmailSendResult restituisce lo stato seguente nell'operazione di posta elettronica eseguita.

Stato Descrizione
NotStarted Questo stato non viene inviato dal servizio in questo momento.
In esecuzione L'operazione di invio di posta elettronica è attualmente in corso e in fase di elaborazione.
Completato L'operazione di invio di posta elettronica è stata completata senza errori e il messaggio di posta elettronica non è disponibile per il recapito. Qualsiasi stato dettagliato sul recapito della posta elettronica oltre questa fase può essere ottenuto tramite Monitoraggio di Azure o tramite Griglia di eventi di Azure. Informazioni su come sottoscrivere eventi di posta elettronica
Non riuscito L'operazione di invio di posta elettronica non ha avuto esito positivo e ha rilevato un errore. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore o dell'annullamento.
Cancellati L'operazione di invio di posta elettronica è stata annullata prima del completamento. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore o dell'annullamento.

Prerequisiti

Il completamento di questo avvio rapido comporta un piccolo costo di pochi centesimi di USD o minore nell'account Azure.

Nota

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

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 servizi di comunicazione Email, accedere alla portale di Azure, individuare la risorsa servizi di comunicazione Email e aprire la scheda Domini di provisioning dal riquadro di spostamento a sinistra.

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

Impostare la directory sulla cartella dell'app appena creata e usare il comando dotnet build per compilare l'applicazione.

cd EmailQuickstart
dotnet build

Installare il pacchetto

Sebbene sia ancora presente nella directory dell'applicazione, installare la libreria client Servizi di comunicazione di Azure Email per il pacchetto .NET usando il dotnet add package comando .

dotnet add package Azure.Communication.Email

Creazione del client di posta elettronica con autenticazione

Aprire Program.cs e sostituire il codice esistente con il codice seguente per aggiungere using direttive per includere lo spazio dei nomi e un punto di partenza per l'esecuzione Azure.Communication.Email del 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)
  {

  }
}
}

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

Invio di posta elettronica di base

Creare il messaggio di posta elettronica

Per inviare un messaggio di posta elettronica, è necessario:

  • Definire l'oggetto e il corpo del messaggio di posta elettronica.
  • Definire l'indirizzo del mittente. Creare il messaggio di posta elettronica con le informazioni del mittente che ottiene l'indirizzo MailFrom dal dominio verificato.
  • Definire l'indirizzo 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, 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 dell'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. Chiamare con Azure.WaitUntil.Complete se il metodo deve attendere il ritorno fino al completamento dell'operazione a esecuzione prolungata nel servizio. Chiamare con Azure.WaitUntil.Started se il metodo deve restituire dopo l'avvio dell'operazione.
  • Il metodo SendAsync restituisce EmailSendOperation che restituisce "Successed" EmailSendStatus se la posta elettronica è in uscita per il recapito e genera 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 del recapito tramite posta elettronica

EmailSendOperation restituisce solo lo stato dell'operazione di posta elettronica. Per ottenere lo stato effettivo del recapito tramite posta elettronica, è possibile sottoscrivere l'evento "EmailDeliveryReportReceived" generato al termine del recapito della posta elettronica. L'evento restituisce lo stato di recapito seguente:

  • Consegnato.
  • non riuscito.
  • Quarantined.

Per informazioni dettagliate, vedere Gestire gli eventi Email.

È anche possibile sottoscrivere Email log operativi che forniscono informazioni correlate alle metriche di recapito per i messaggi inviati dal servizio Email.

  • Email i log operativi invia posta elettronica: fornisce informazioni dettagliate correlate alle richieste di posta elettronica inviate dal servizio Email.
  • Email log operativi di aggiornamento dello stato: fornisce aggiornamenti dello stato di recapito a livello di messaggio e destinatari correlati alle richieste di posta elettronica inviate dal servizio Email.

Accedere ai log per Email servizio di comunicazione.

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

Iniziare a usare Servizi di comunicazione di Azure usando la libreria client JS di Servizi di comunicazione Email per inviare messaggi Email.

Suggerimento

Iniziare l'esperienza di invio tramite posta elettronica con Servizi di comunicazione di Azure ignorando direttamente l'Email Basic Email Invio e Advanced Email Invio di codice di esempio in GitHub.

Informazioni sul modello a oggetti di posta elettronica

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità della libreria client di Servizi di comunicazione di Azure Email 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 di tipo MIME dell'allegato di posta elettronica e i dati binari per il contenuto.
EmailClient Questa classe è necessaria per tutte le funzionalità di 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 la destinazione di una versione API specifica.
EmailContent Questa classe contiene l'oggetto e il corpo del messaggio di posta elettronica. È necessario specificare almeno uno dei contenuti PlainText o Html.
EmailCustomHeader Questa classe consente l'aggiunta di un nome e una coppia di valori per un'intestazione personalizzata. Email importanza può essere specificata anche tramite queste intestazioni usando il nome di intestazione 'x-priority' o 'x-msmail-priority'.
EmailMessage Questa classe combina il mittente, il contenuto e i destinatari. Anche le intestazioni personalizzate, gli allegati e gli indirizzi di posta elettronica di risposta possono essere aggiunti facoltativamente.
EmailRecipients Questa classe contiene elenchi di oggetti EmailAddress per i destinatari del messaggio di posta elettronica, inclusi gli elenchi facoltativi per & i destinatari cccc.
EmailSendResult Questa classe contiene i risultati dell'operazione di invio di posta elettronica. Ha un ID operazione, lo stato dell'operazione e l'oggetto errore (quando applicabile).
EmailSendStatus Questa classe rappresenta il set di stati di un'operazione di invio tramite posta elettronica.

EmailSendResult restituisce lo stato seguente nell'operazione di posta elettronica eseguita.

Nome stato Descrizione
isStarted Restituisce true se l'operazione di invio di posta elettronica è attualmente in corso e viene elaborata.
Iscompleted Restituisce true se l'operazione di invio di posta elettronica è stata completata senza errori e il messaggio di posta elettronica non è attivo per il recapito. Qualsiasi stato dettagliato sul recapito della posta elettronica oltre questa fase può essere ottenuto tramite Monitoraggio di Azure o tramite Griglia di eventi di Azure. Informazioni su come sottoscrivere eventi di posta elettronica
result Proprietà che esiste se l'operazione di invio di posta elettronica è stata completata.
error Proprietà che esiste se l'operazione di invio di posta elettronica non è riuscita e ha rilevato un errore. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore o dell'annullamento.
isCanceled True se l'operazione di invio di posta elettronica è stata annullata prima del completamento. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore o dell'annullamento.

Prerequisiti

Il completamento di questo avvio rapido comporta un piccolo costo di pochi centesimi di USD o minore nell'account Azure.

Nota

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

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 Email, accedere alla portale di Azure, individuare la risorsa servizi di comunicazione Email e aprire la scheda Provision domain 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-email.js nella directory radice del progetto. Modificare la proprietà "main" in package.json in "send-email.js". La sezione seguente illustra come aggiungere il codice sorgente per questa guida introduttiva al file appena creato.

Installare il pacchetto

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

npm install @azure/communication-email --save

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

Creazione del client di posta elettronica con autenticazione

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

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 usando il pacchetto dotenv. Usare il comando per installare il npm install pacchetto dotenv. Informazioni su come gestire la stringa di connessione della risorsa.

npm install dotenv

Aggiungere il codice seguente a 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);

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

Invio di posta elettronica di base

Inviare un messaggio di posta elettronica

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


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

Apportare 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 Java Email SDK di Servizi di comunicazione per inviare messaggi di Email.

Suggerimento

Iniziare subito l'esperienza di invio di messaggi di posta elettronica con Servizi di comunicazione di Azure ignorando direttamente l'Email Basic Email Sending and Advanced Email Sending sample code on GitHub (Invio di codice di esempio in GitHub).

Informazioni sul modello a oggetti di posta elettronica

Le classi e le interfacce seguenti gestiscono alcune delle principali funzionalità di Servizi di comunicazione di Azure Email SDK 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 e una stringa di byte di contenuto.
EmailClient Questa classe è necessaria per tutte le funzionalità di 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. È 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. Ha un ID operazione, lo stato dell'operazione e l'oggetto errore (se applicabile).
EmailSendStatus Questa classe rappresenta il set di stati di un'operazione di invio tramite posta elettronica.

EmailSendResult restituisce lo stato seguente nell'operazione di posta elettronica eseguita.

Nome stato Descrizione
NOT_STARTED Questo stato non viene inviato al momento dal servizio.
IN_PROGRESS L'operazione di invio tramite 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 non è disponibile per il recapito. Qualsiasi stato dettagliato sul recapito della posta elettronica oltre questa fase può essere ottenuto tramite Monitoraggio di Azure o tramite Griglia di eventi di Azure. Informazioni su come sottoscrivere eventi di posta elettronica
FAILED L'operazione di invio tramite posta elettronica non è riuscita e ha rilevato un errore. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore o dell'annullamento.
USER_CANCELLED L'operazione di invio tramite posta elettronica è stata annullata prima del completamento. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore o dell'annullamento.

Prerequisiti

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 Aggiungere domini verificati personalizzati a Email Servizio di comunicazione.

Controllo dei prerequisiti

  • In un terminale o in una finestra di comando eseguire mvn -v per verificare che Maven sia installato.
  • Per visualizzare i domini verificati con la risorsa di Servizi di comunicazione di Email, accedere al portale di Azure. Individuare la risorsa Email Servizi di comunicazione e aprire la scheda Provision domains (Effettuare il provisioning dei domini) nel riquadro di spostamento a sinistra.

Configurare l'ambiente dell'applicazione

Per configurare un ambiente per l'invio di messaggi di posta elettronica, seguire questa procedura 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 artifactId valore. 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 direttive di importazione 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.PollResponse;
import com.azure.core.util.polling.SyncPoller;

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

Creazione del client di posta elettronica con l'autenticazione

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

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

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

// 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 semplicità, questa guida introduttiva usa stringhe di connessione, ma negli ambienti di produzione è consigliabile usare le entità servizio.

Invio di posta elettronica di base

Per inviare un messaggio di posta elettronica, chiamare la beginSend funzione da EmailClient. Questo metodo restituisce un poller, che può essere usato per controllare lo stato dell'operazione e recuperare il risultato al termine.

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

try
{
    SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null);

    PollResponse<EmailSendResult> pollResponse = null;

    Duration timeElapsed = Duration.ofSeconds(0);

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

Eseguire queste sostituzioni nel codice:

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

Eseguire il codice

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

    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 Python Email SDK di Servizi di comunicazione per inviare messaggi di Email.

Suggerimento

Iniziare subito l'esperienza di invio di messaggi di posta elettronica con Servizi di comunicazione di Azure ignorando direttamente l'Email Basic Email Sending and Advanced Email Sending sample code on GitHub (Invio di codice di esempio in GitHub).

Informazioni sul modello a oggetti di posta elettronica

L'oggetto di risposta del modello & di messaggio JSON seguente illustra alcune delle principali funzionalità di Servizi di comunicazione di Azure Email SDK 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", "Failed", and "Canceled".
    "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 response.status valori sono illustrati più avanti nella tabella seguente.

Nome stato Descrizione
InProgress L'operazione di invio tramite 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 non è disponibile per il recapito. Qualsiasi stato dettagliato sul recapito della posta elettronica oltre questa fase può essere ottenuto tramite Monitoraggio di Azure o tramite Griglia di eventi di Azure. Informazioni su come sottoscrivere eventi di posta elettronica
Non riuscito L'operazione di invio tramite posta elettronica non è riuscita e ha rilevato un errore. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore o dell'annullamento.
Cancellati L'operazione di invio tramite posta elettronica è stata annullata prima del completamento. Il messaggio di posta elettronica non è stato inviato. Il risultato contiene un oggetto errore con altri dettagli sul motivo dell'errore o dell'annullamento.

Prerequisiti

Il completamento di questa guida introduttiva comporta un costo ridotto di pochi centesimi di USD o inferiore nell'account Azure.

Nota

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

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 di Email, accedere al portale di Azure. Individuare la risorsa Email Servizi di comunicazione e aprire la scheda Provision domains (Effettuare il provisioning dei domini) nel riquadro di spostamento a sinistra.

Configurare l'ambiente dell'applicazione

Per configurare un ambiente per l'invio di messaggi di posta elettronica, seguire questa procedura 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 si aggiunge tutto il codice sorgente per questa guida introduttiva al file di send-email.py creato.

Installare il pacchetto

Anche se è ancora nella directory dell'applicazione, installare il pacchetto Servizi di comunicazione di Azure Email SDK per Python usando il comando seguente.

pip install azure-communication-email

Creazione del client di posta elettronica con l'autenticazione

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

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

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

Invio di posta elettronica di base

Inviare un messaggio di posta elettronica

Per inviare un messaggio di posta elettronica, è necessario:

  • Costruire il messaggio con i valori seguenti:
    • senderAddress: indirizzo di posta elettronica del mittente valido, disponibile nel campo MailFrom nel riquadro di panoramica del dominio collegato alla risorsa di Servizi di comunicazione Email.
    • recipients: oggetto con un elenco di destinatari di posta elettronica e, facoltativamente, elenchi di destinatari di posta elettronica 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())

Eseguire queste sostituzioni nel codice:

  • Sostituire <emailalias@emaildomain.com> con l'indirizzo di posta elettronica a cui si vuole 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 di begin_send 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 (app per la logica) attiva e un flusso di lavoro oppure creare una nuova risorsa e un nuovo flusso di lavoro dell'app per la logica con il trigger che si vuole usare. Attualmente, il connettore Servizi di comunicazione di Azure Email fornisce 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 .

  • Una risorsa Servizi di comunicazione di Azure Email con un dominio configurato o un dominio personalizzato.

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

Invio di un messaggio di posta elettronica

Per aggiungere un nuovo passaggio al flusso di lavoro usando il connettore Servizi di comunicazione di Azure Email, 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 questi passaggi, selezionare il segno più (+) e selezionare Aggiungi un'azione.

    2. Nella casella di ricerca Scegli un'operazione selezionare Standard. Nella casella di ricerca immettere Servizi di comunicazione Email.

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

      Screenshot che mostra l'azione Invia messaggio di posta elettronica del connettore Servizi di comunicazione di Azure Email.

    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 questi passaggi, selezionare il segno più (+) e selezionare Aggiungi un'azione.

    2. Nella casella di ricerca Scegliere un'operazione selezionare Azure. Nella casella di ricerca immettere Servizi di comunicazione Email.

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

  2. Specificare un nome per la connessione.

  3. Immettere la stringa di connessione per la risorsa del servizio comunicazioni di Azure. Per trovare questa stringa, seguire questa procedura:

    1. Nel portale di Azure aprire la risorsa del servizio di comunicazione di Azure.

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

      Screenshot che mostra la Servizi di comunicazione di Azure stringa di connessione.

  4. Al termine, selezionare Crea.

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

    Screenshot che mostra l'input dell'azione Invia messaggio di posta elettronica Servizi di comunicazione di Azure Email connettore.

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

Testare il flusso di lavoro

In base al fatto che si disponga di un flusso di lavoro a consumo o Standard, avviare manualmente il flusso di lavoro:

  • Consumo: sulla barra degli strumenti della finestra di progettazione selezionare Esegui esecuzione trigger>.
  • Standard: nel menu del flusso di lavoro selezionare Panoramica. Sulla barra degli strumenti selezionare Esegui esecuzione trigger>.

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 dopo l'esecuzione del flusso di lavoro.

Dovrebbe essere visualizzato un messaggio di posta elettronica all'indirizzo specificato. Inoltre, è possibile usare l'azione Ottieni stato messaggio di posta elettronica per controllare lo stato dei messaggi di posta elettronica inviati tramite l'azione Invia messaggio di posta elettronica . Per altre azioni, vedere la documentazione di riferimento sul connettore Servizi di comunicazione di Azure Email.

Pulire le risorse del flusso di lavoro

Per pulire il flusso di lavoro dell'app per la logica e le risorse correlate, vedere come pulire le risorse dell'app per la logica a consumo o come pulire le risorse dell'app per la logica Standard.

Risoluzione dei problemi

Recapito Email

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

Il risultato dell'esito positivo restituito dal polling per lo stato dell'operazione di invio convalida solo il fatto che il messaggio di posta elettronica sia stato inviato correttamente per il recapito. Per ottenere informazioni aggiuntive sullo stato del recapito alla fine del destinatario, è necessario fare riferimento a come gestire gli eventi di posta elettronica.

Limitazione Email

Se si noterà che l'applicazione è in sospeso, potrebbe essere dovuta all'invio di messaggi di posta elettronica limitati. È possibile gestirlo tramite la registrazione o implementando un criterio personalizzato.

Nota

Questa configurazione sandbox consente agli sviluppatori di iniziare a creare l'applicazione. È possibile richiedere gradualmente di aumentare il volume di invio dopo che l'applicazione è pronta per essere attiva. Inviare una richiesta di supporto per aumentare il limite di invio desiderato se è necessario inviare un volume di messaggi che superano i limiti di frequenza.

Pulire le risorse del servizio di comunicazione di Azure

Per pulire e rimuovere una sottoscrizione di Servizi di comunicazione, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di altre risorse associate. Vedere altre informazioni sulla pulizia delle risorse.

Passaggi successivi

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