Rychlý start: Ruční dotazování na stav e-mailu při odesílání e-mailu

V tomto rychlém startu se dozvíte, jak se ručně dotazovat na stav e-mailu při odesílání e-mailů pomocí našich e-mailových sad SDK.

Začněte se službou Azure Communication Services pomocí e-mailové klientské knihovny komunikačních služeb .NET k odesílání e-mailových zpráv.

Tip

Přeskočením přímo na Základní odesílání e-mailů a pokročilým odesíláním e-mailů na GitHubu můžete začít s prostředím pro odesílání e-mailů pomocí Azure Communication Services.

Principy modelu objektu e-mailu

Následující třídy a rozhraní zpracovávají některé z hlavních funkcí e-mailové knihovny e-mailových služeb Azure pro C#.

Název	Popis
EmailAddress	Tato třída obsahuje e-mailovou adresu a možnost zobrazovaného jména.
Připojení e-mailu	Tato třída vytvoří e-mailovou přílohu přijetím jedinečného ID, řetězcem typu MIME přílohy e-mailu, binárními daty pro obsah a volitelným ID obsahu, které ji definuje jako vloženou přílohu.
EmailClient	Tato třída je potřebná pro všechny funkce e-mailu. Vytvoříte instanci s připojovací řetězec a použijete ji k odesílání e-mailových zpráv.
EmailClientOptions	Tuto třídu je možné přidat do instance EmailClient pro cílení na konkrétní verzi rozhraní API.
EmailContent	Tato třída obsahuje předmět a text e-mailové zprávy. Musíte zadat alespoň jeden z obsahu PlainText nebo Html.
EmailCustomHeader	Tato třída umožňuje přidání dvojice názvů a hodnot pro vlastní hlavičku. Důležitost e-mailu lze také zadat prostřednictvím těchto hlaviček pomocí názvu záhlaví x-priority nebo x-msmail-priority.
EmailMessage	Tato třída kombinuje odesílatele, obsah a příjemce. Můžete také přidat vlastní záhlaví, přílohy a e-mailové adresy pro odpovědi.
E-mailRecipients	Tato třída obsahuje seznamy objektů EmailAddress pro příjemce e-mailové zprávy, včetně volitelných seznamů pro příjemce kopie a skryté kopie.
EmailSendOperation	Tato třída představuje asynchronní operaci odeslání e-mailu a je vrácena z volání rozhraní API pro odesílání e-mailů.
EmailSendResult	Tato třída obsahuje výsledky operace odeslání e-mailu. Má ID operace, stav operace a objekt chyby (pokud je k dispozici).

Funkce EmailSendResult vrátí následující stav provedené e-mailové operace.

Status	Popis
NotStarted	V tuto chvíli tento stav neodesíláme z naší služby.
Spuštěno	Právě probíhá a zpracovává se operace odeslání e-mailu.
Úspěšný	Operace odeslání e-mailu se dokončila bez chyby a e-mail je k doručení. Jakýkoli podrobný stav o doručení e-mailu nad rámec této fáze je možné získat prostřednictvím služby Azure Monitor nebo prostřednictvím služby Azure Event Grid. Zjistěte, jak se přihlásit k odběru e-mailových událostí.
Neúspěšný	Operace odeslání e-mailu nebyla úspěšná a došlo k chybě. E-mail se neodeslal. Výsledek obsahuje objekt chyby s dalšími podrobnostmi o důvodu selhání.

Požadavky

• Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
• Nejnovější verze klientské knihovny .NET Core pro váš operační systém.
• Prostředek služby Azure Email Communication Services vytvořený a připravený se zřízenou doménou Začínáme s vytvářením prostředku pro e-mailovou komunikaci
• Aktivní prostředek komunikační služby připojený k e-mailové doméně a připojovacímu řetězci. Začínáme připojením e-mailového prostředku pomocí komunikačního prostředku

Dokončením tohoto rychlého startu se v účtu Azure účtují malé náklady na pár centů nebo méně USD.

Poznámka:

Můžeme také poslat e-mail z naší vlastní ověřené domény. Přidání vlastních ověřených domén do e-mailové komunikační služby

Kontrola požadovaných součástí

• V terminálu nebo příkazovém okně spusťte dotnet příkaz a zkontrolujte, jestli je nainstalovaná klientská knihovna .NET.
• Pokud chcete zobrazit subdomény přidružené k vašemu prostředku e-mailové komunikační služby, přihlaste se k webu Azure Portal, vyhledejte prostředek e-mailové komunikační služby a v levém navigačním podokně otevřete kartu Zřizovací domény .

Vytvoření nové aplikace jazyka C#

V okně konzoly (například cmd, PowerShell nebo Bash) pomocí dotnet new příkazu vytvořte novou konzolovou aplikaci s názvem EmailQuickstart. Tento příkaz vytvoří jednoduchý projekt "Hello World" C# s jedním zdrojovým souborem: Program.cs.

dotnet new console -o EmailQuickstart

Změňte adresář na nově vytvořenou složku aplikace a pomocí dotnet build příkazu zkompilujte aplikaci.

cd EmailQuickstart
dotnet build

Nainstalujte balíček .

V adresáři aplikace nainstalujte pomocí příkazu klientskou knihovnu e-mailových služeb Azure Communication Services pro balíček dotnet add package .NET.

dotnet add package Azure.Communication.Email

Vytvoření e-mailového klienta s ověřováním

Otevřete Program.cs a nahraďte stávající kód následujícími direktivami pro přidání using direktiv pro zahrnutí Azure.Communication.Email oboru názvů a výchozího bodu pro spuštění programu.

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

    }
  }
}

Pro ověřování e-mailového klienta je k dispozici několik různých možností:

Připojovací řetězec

Otevřete Program.cs v textovém editoru a nahraďte text Main metody kódem, který inicializuje EmailClient připojovací řetězec. Následující kód načte připojovací řetězec pro prostředek z proměnné prostředí s názvem COMMUNICATION_SERVICES_CONNECTION_STRING. Zjistěte, jak spravovat připojovací řetězec vašeho prostředku.

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

Azure Active Directory

Pokud chcete provést ověření pomocí Azure Active Directory, pomocí příkazu nainstalujte Azure.Identity balíček knihovny pro .NET dotnet add package .

dotnet add package Azure.Identity

Otevřete Program.cs v textovém editoru a nahraďte text Main metody kódem pro inicializaci EmailClient pomocí DefaultAzureCredential. Sada Azure Identity SDK načítá hodnoty ze tří proměnných prostředí za běhu za účelem ověření aplikace. Zjistěte, jak vytvořit zaregistrovanou aplikaci Azure Active Directory a nastavit proměnné prostředí.

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

E-mailové klienty je také možné ověřit pomocí azureKeyCredential. key Obě možnosti mohou endpoint být založeny na podokně Klíče v části Nastavení v prostředku komunikační služby.

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

var emailClient = new EmailClient(endpoint, key);

Odesílání asynchronních e-mailů a dotazování na stav odeslání e-mailu

Když zavoláte SendAsync s Azure.WaitUntil.Started, vaše metoda se vrátí zpět po spuštění operace. Metoda vrátí EmailSendOperation objekt. K aktualizaci stavu e-mailové operace můžete volat metodu UpdateStatusAsync.

Vrácený Objekt EmailSendOperation obsahuje Objekt EmailSendStatus, který obsahuje:

• Aktuální stav operace Odeslání e-mailu
• Objekt chyby s podrobnostmi o selhání, pokud je aktuální stav ve stavu selhání.

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

Spusťte aplikaci z adresáře aplikace pomocí dotnet run příkazu.

dotnet run

Ukázkový kód

Ukázkovou aplikaci si můžete stáhnout z GitHubu.

Řešení problému

Doručování e-mailů

Pokud chcete vyřešit problémy související s doručováním e-mailů, můžete získat stav doručení e-mailu a zaznamenat podrobnosti o doručení.

Důležité

Výsledek úspěchu vrácený dotazem na stav operace odeslání ověří pouze skutečnost, že se e-mail úspěšně odeslal k doručení. Pokud chcete získat další informace o stavu doručení na konci příjemce, budete muset odkazovat na zpracování e-mailových událostí.

Omezení e-mailu

Pokud zjistíte, že aplikace je zablokovaná, může to být kvůli omezování odesílání e-mailů. Můžete to zpracovat prostřednictvím protokolování nebo implementací vlastních zásad.

Poznámka:

Toto nastavení sandboxu pomáhá vývojářům začít vytvářet aplikaci. Jakmile je aplikace připravená k živému provozu, můžete postupně požádat o zvýšení odesílajícího svazku. Odešlete žádost o podporu pro zvýšení požadovaného limitu odesílání, pokud požadujete odeslání objemu zpráv překračujících limity rychlosti.

Vyčištění prostředků služby Azure Communication Service

Pokud chcete vyčistit a odebrat předplatné služby Communication Services, můžete odstranit prostředek nebo skupinu prostředků. Odstraněním skupiny prostředků se odstraní také všechny ostatní prostředky, které jsou k ní přidružené. Přečtěte si další informace o čištění prostředků.

Další kroky

V tomto rychlém startu jste zjistili, jak ručně dotazovat na stav při odesílání e-mailů pomocí Azure Communication Services.

Můžete také chtít:

• Přečtěte si, jak odeslat e-mail více příjemcům.
• Další informace o odesílání e-mailů s přílohami
• Seznámení s e-mailovou klientskou knihovnou