Schnellstart: Manuelles Abfragen des E-Mail-Status beim Senden von E-Mails

Artikel
05/05/2023

In diesem Schnellstart erfahren Sie, wie Sie beim Senden von E-Mails mithilfe unserer Email SDKs manuell den E-Mail-Status abfragen.

Machen Sie die ersten Schritte mit Azure Communication Services, indem Sie die .NET-Clientbibliothek für E-Mail von Communication Services nutzen, um E-Mail-Nachrichten zu senden.

Tipp

Starten Sie Ihre E-Mail-Sendeerfahrung mit Azure Communication Services, indem Sie direkt zum Beispielcode Einfaches Senden von E-Mails and Erweitertes Senden von E-Mails auf GitHub überspringen.

Grundlegendes zum E-Mail-Objektmodell

Die folgenden Klassen und Schnittstellen werden für einige der wichtigsten Features der C#-Clientbibliothek für E-Mail von Azure Communication Services verwendet.

Name	BESCHREIBUNG
EmailAddress	Diese Klasse enthält eine E-Mail-Adresse und eine Option für einen Anzeigenamen.
EmailAttachment	In dieser Klasse wird eine E-Mail-Anlage erstellt, indem eine eindeutige ID, eine MIME-Typ-Zeichenfolge für die E-Mail-Anlage, binäre Daten für Inhalte und eine optionale Inhalts-ID akzeptiert werden, um sie als Inline-Anlage zu definieren.
EmailClient	Diese Klasse ist für sämtliche E-Mail-Funktionen erforderlich. Sie instanziieren sie mit Ihrer Verbindungszeichenfolge und verwenden sie zum Senden von E-Mail-Nachrichten.
EmailClientOptions	Diese Klasse kann der EmailClient-Instanziierung für eine bestimmte API-Version hinzugefügt werden.
EmailContent	Diese Klasse enthält den Betreff und Text der E-Mail-Nachricht. Sie müssen mindestens eine der Inhaltsoptionen „PlainText“ oder „Html“ angeben.
EmailCustomHeader	Diese Klasse ermöglicht das Hinzufügen eines Name-Wert-Paars für einen benutzerdefinierten Header. Die Wichtigkeit von E-Mails kann auch über diese Header mithilfe des Headernamens „x-priority“ oder „x-msmail-priority“ angegeben werden.
EmailMessage	Diese Klasse kombiniert Absender, Inhalt und Empfänger. Benutzerdefinierte Header, Anlagen und Antwort-E-Mail-Adressen können optional hinzugefügt werden.
EmailRecipients	Diese Klasse enthält Listen von EmailAddress-Objekten für Empfängerinnen der E-Mail-Nachricht, einschließlich optionaler Listen für CC- und BCC-Empfängerinnen.
EmailSendOperation	Diese Klasse stellt den asynchronen E-Mail-Sendevorgang dar und wird vom Aufruf der E-Mail-Sende-API zurückgegeben.
EmailSendResult	Diese Klasse enthält die Ergebnisse des E-Mail-Sendevorgangs. Sie weist eine Vorgangs-ID, einen Vorgangsstatus und ein Fehlerobjekt (falls zutreffend) auf.

EmailSendResult gibt den folgenden Status für den ausgeführten E-Mail-Vorgang zurück.

Status	BESCHREIBUNG
NotStarted	Wir senden diesen Status derzeit nicht von unserem Dienst.
Wird ausgeführt	Der E-Mail-Sendevorgang wird derzeit ausgeführt und verarbeitet.
Erfolgreich	Der E-Mail-Sendevorgang wurde ohne Fehler abgeschlossen, und die E-Mail ist zur Zustellung raus. Der detaillierte Status zur E-Mail-Übermittlung über diese Phase hinaus kann entweder über Azure Monitor oder über Azure Event Grid abgerufen werden. Informationen zum Abonnieren von E-Mail-Ereignissen
Fehler	Der E-Mail-Sendevorgang war nicht erfolgreich, und es ist ein Fehler aufgetreten. Die E-Mail wurde nicht gesendet. Das Ergebnis enthält ein Fehlerobjekt mit weiteren Details zum Fehlergrund.

Voraussetzungen

Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
Die aktuelle Version der .NET Core-Clientbibliothek für Ihr Betriebssystem.
Eine E-Mail-Communication Service-Ressource wurde in Azure erstellt und steht mit einer bereitgestellten Domänen zur Verfügung Erste Schritte mit dem Erstellen einer E-Mail-Communication Service-Ressource
Eine aktive Communication Services-Ressource, die mit der E-Mail-Domäne und einer Verbindungszeichenfolge verbunden ist. Erste Schritte nach Verbinden der E-Mail-Ressource mit einer Kommunikationsressource

Im Rahmen dieses Schnellstarts fallen in Ihrem Azure-Konto ggf. geringfügige Kosten im Centbereich an.

Hinweis

Wir können auch eine E-Mail von unserer eigenen verifizierten Domäne senden. Hinzufügen benutzerdefinierter überprüfter Domänen zu Email Communication Service

Prüfen der Voraussetzungen

Führen Sie in einem Terminal- oder Befehlsfenster den Befehl dotnet aus, um sich zu vergewissern, dass die .NET-Clientbibliothek installiert ist.
Melden Sie sich zum Anzeigen der Ihrer E-Mail-Communication Service-Ressource zugeordneten Unterdomänen beim Azure-Portal an. Suchen Sie nach Ihrer E-Mail-Communication Service-Ressource, und öffnen Sie im linken Navigationsbereich die Registerkarte Domänen bereitstellen.

Erstellen einer neuen C#-Anwendung

Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen EmailQuickstart. Dieser Befehl erstellt ein einfaches „Hallo Welt“-C#-Projekt mit einer einzigen Quelldatei: Program.cs.

dotnet new console -o EmailQuickstart

Wechseln Sie zum neu erstellten App-Ordner, und verwenden Sie den Befehl dotnet build, um Ihre Anwendung zu kompilieren.

cd EmailQuickstart
dotnet build

Installieren des Pakets

Installieren Sie im Anwendungsverzeichnis mithilfe des Befehls dotnet add package das .NET-Paket der Clientbibliothek für E-Mail von Azure Communication Services.

dotnet add package Azure.Communication.Email

Erstellen des E-Mail-Clients mit Authentifizierung

Öffnen Sie Program.cs, und ersetzen Sie den vorhandenen Code durch den folgenden, um using-Anweisungen für die Einbeziehung des Azure.Communication.Email-Namespace und einen Ausgangspunkt zur Ausführung Ihres Programms hinzuzufügen.


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

    }
  }
}

Für die Authentifizierung eines E-Mail-Clients stehen verschiedene Optionen zur Verfügung:

Öffnen Sie Program.cs in einem Text-Editor, und ersetzen Sie den Text der Methode Main durch Code zum Initialisieren eines SMS-Clients (EmailClient) mit Ihrer Verbindungszeichenfolge. Im folgenden Code wird die Verbindungszeichenfolge für die Ressource aus einer Umgebungsvariablen namens COMMUNICATION_SERVICES_CONNECTION_STRING abgerufen. Informationen zur Verwaltung der Verbindungszeichenfolge Ihrer Ressource.

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

Installieren Sie für die Authentifizierung mithilfe von Azure Active Directory das Azure.Identity-Bibliothekspaket für .NET mit dem Befehl dotnet add package.

dotnet add package Azure.Identity

Öffnen Sie Program.cs in einem Texteditor, und ersetzen Sie den Text der Main-Methode durch Code, um einen beliebigen EmailClient mit DefaultAzureCredential zu initialisieren. Über das Azure Identity SDK werden zur Laufzeit Werte aus drei Umgebungsvariablen gelesen, um die Anwendung zu authentifizieren. Erfahren Sie, wie Sie eine in Azure Active Directory registrierte Anwendung erstellen und die Umgebungsvariablen festlegen.

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

E-Mail-Clients können auch mithilfe von AzureKeyCredential authentifiziert werden. Sowohl der key als auch der endpoint können im Bereich „Schlüssel“ unter „Einstellungen“ in Ihrer Communication Services-Ressource erstellt werden.

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

var emailClient = new EmailClient(endpoint, key);

Asynchrones Senden von E-Mails und Abfragen des E-Mail-Sendestatus

Wenn Sie SendAsync mit Azure.WaitUntil.Started aufrufen, kehrt Ihre Methode nach dem Starten des Vorgangs zurück. Die Methode gibt ein EmailSendOperation-Objekt zurück. Sie können die UpdateStatusAsync-Methode aufrufen, um den E-Mail-Betriebsstatus zu aktualisieren.

Das zurückgegebene EmailSendOperation-Objekt enthält ein EmailSendStatus-Objekt, das Folgendes enthält:

Aktueller Status des E-Mail-Sendevorgangs.
Ein Fehlerobjekt mit Fehlerdetails, wenn sich der aktuelle Status ein fehlerbehafteter Zustand ist.


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

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

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

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

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

Führen Sie die Anwendung mit dem Befehl dotnet run aus dem Anwendungsverzeichnis aus.

dotnet run

Beispielcode

Sie können die Beispiel-App von GitHub herunterladen.

Problembehandlung

E-Mail-Zustellung

Zur Behebung von Problemen im Zusammenhang mit der E-Mail-Zustellung können Sie den Status der E-Mail-Zustellung abrufen, um Zustellungsdetails zu erfassen.

Wichtig

Das Erfolgsergebnis, das durch Abfragen des Sendestatus zurückgegeben wird, beweist nur, dass die E-Mail erfolgreich zur Zustellung gesendet wurde. Um zusätzliche Informationen über den Zustellungsstatus am Empfängerende zu erhalten, müssen Sie Behandlung von E-Mail-Ereignissen lesen.

E-mail-Drosselung

Wenn Sie sehen, dass Ihre Anwendung hängt, kann dies darauf zurückzuführen sein, dass das Senden von E-Mails gedrosselt wurde. Sie können dies über die Protokollierung oder die Implementierung einer benutzerdefinierten Richtlinie beheben.

Hinweis

Dieses Sandboxsetup hilft Entwicklern beim Erstellen der Anwendung. Sie können eine schrittweise Erhöhung des Sendevolumens anfordern, sobald die Anwendung einsatzbereit ist. Übermitteln Sie eine Supportanfrage, um das von Ihnen gewünschte Sendelimit zu erhöhen, wenn Sie ein Nachrichtenvolumen senden müssen, das die Ratenbegrenzungen überschreitet.

Bereinigen von Azure Communication Service-Ressourcen

Wenn Sie ein Communication Services-Abonnement bereinigen und entfernen möchten, können Sie die Ressource oder die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden auch alle anderen Ressourcen gelöscht, die ihr zugeordnet sind. Weitere Informationen zum Bereinigen von Ressourcen finden Sie hier.

Nächste Schritte

In diesem Schnellstart haben Sie erfahren, wie Sie den Sendestatus von E-Mails mithilfe von Azure Communication Services manuell abfragen.

Freigeben über