Snabbstart: Sök manuellt efter e-poststatus när du skickar e-post

I den här snabbstarten får du lära dig hur du manuellt avsöker efter e-poststatus när du skickar e-post med hjälp av våra E-post-SDK:er.

Kom igång med Azure Communication Services med hjälp av klientbiblioteket för Communication Services .NET-e-post för att skicka e-postmeddelanden.

Dricks

Kom igång med att skicka e-post med Azure Communication Services genom att hoppa direkt till exempelkoden Grundläggande e-postsändning och Avancerad e-postsändning på GitHub.

Förstå e-postobjektmodellen

Följande klasser och gränssnitt hanterar några av de viktigaste funktionerna i Azure Communication Services e-postklientbibliotek för C#.

Name	beskrivning
EmailAddress	Den här klassen innehåller en e-postadress och ett alternativ för ett visningsnamn.
EmailAttachment	Den här klassen skapar en e-postbilaga genom att acceptera ett unikt ID, MIME-typsträng för e-postbilagor, binära data för innehåll och ett valfritt innehålls-ID för att definiera det som en infogad bifogad fil.
EmailClient	Den här klassen behövs för alla e-postfunktioner. Du instansierar den med din anslutningssträng och använder den för att skicka e-postmeddelanden.
EmailClientOptions	Den här klassen kan läggas till i e-postklientinstansiationen för att rikta in sig på en specifik API-version.
EmailContent	Den här klassen innehåller ämnet och brödtexten i e-postmeddelandet. Du måste ange minst ett av PlainText- eller Html-innehåll
EmailCustomHeader	Den här klassen tillåter tillägg av ett namn och värdepar för en anpassad rubrik. E-postprioritet kan också anges via dessa rubriker med rubriknamnet "x-priority" eller "x-msmail-priority"
EmailMessage	Den här klassen kombinerar avsändaren, innehållet och mottagarna. Anpassade rubriker, bifogade filer och svarsadresser kan också läggas till.
EmailRecipients	Den här klassen innehåller listor över EmailAddress-objekt för mottagare av e-postmeddelandet, inklusive valfria listor för CC & BCC-mottagare.
EmailSendOperation	Den här klassen representerar den asynkrona e-postsändningsåtgärden och returneras från API-anropet för att skicka e-post.
EmailSendResult	Den här klassen innehåller resultatet av e-postsändningsåtgärden. Den har ett åtgärds-ID, åtgärdsstatus och felobjekt (om tillämpligt).

EmailSendResult returnerar följande status för den e-poståtgärd som utförts.

Status	beskrivning
NotStarted	Vi skickar inte den här statusen från vår tjänst just nu.
Körs	E-postsändningsåtgärden pågår och bearbetas.
Klart	E-postsändningsåtgärden har slutförts utan fel och e-postmeddelandet är ute för leverans. Detaljerad status om e-postleveransen utöver det här steget kan hämtas antingen via Azure Monitor eller via Azure Event Grid. Lär dig hur du prenumererar på e-posthändelser
Misslyckad	Åtgärden för att skicka e-post lyckades inte och påträffade ett fel. E-postmeddelandet skickades inte. Resultatet innehåller ett felobjekt med mer information om orsaken till felet.

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
• Den senaste versionen av .NET Core-klientbiblioteket för ditt operativsystem.
• En Azure Email Communication Services-resurs som skapats och är redo med en etablerad domän Kom igång med att skapa en e-postkommunikationsresurs
• En aktiv Communication Services-resurs som är ansluten till e-postdomänen och en anslutningssträng. Kom igång genom att ansluta e-postresurs med en kommunikationsresurs

Att slutföra den här snabbstarten medför en liten kostnad på några USD cent eller mindre i ditt Azure-konto.

Kommentar

Vi kan också skicka ett e-postmeddelande från vår egen verifierade domän. Lägg till anpassade verifierade domäner i e-postkommunikationstjänsten.

Kravkontroll

• I ett terminal- eller kommandofönster kör du dotnet kommandot för att kontrollera att .NET-klientbiblioteket är installerat.
• Om du vill visa de underdomäner som är associerade med resursen För e-postkommunikationstjänster loggar du in på Azure Portal, letar upp resursen För e-postkommunikationstjänster och öppnar fliken Etablera domäner i det vänstra navigeringsfönstret.

Skapa ett nytt C#-program

I ett konsolfönster (till exempel cmd, PowerShell eller Bash) använder du dotnet new kommandot för att skapa en ny konsolapp med namnet EmailQuickstart. Det här kommandot skapar ett enkelt "Hello World"-C#-projekt med en enda källfil: Program.cs.

dotnet new console -o EmailQuickstart

Ändra katalogen till den nyligen skapade appmappen dotnet build och använd kommandot för att kompilera programmet.

cd EmailQuickstart
dotnet build

Installera -paketet

Installera Azure Communication Services e-postklientbibliotek för .NET-paketet med hjälp av kommandot medan du fortfarande är i programkatalogen dotnet add package .

dotnet add package Azure.Communication.Email

Skapa e-postklienten med autentisering

Öppna Program.cs och ersätt den befintliga koden med följande för att lägga using till direktiv för att inkludera Azure.Communication.Email namnområdet och en startpunkt för körning för programmet.

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

    }
  }
}

Det finns några olika alternativ för att autentisera en e-postklient:

Anslutningssträng

Öppna Program.cs i en textredigerare och ersätt metodens Main brödtext med kod för att initiera en EmailClient med din anslutningssträng. Följande kod hämtar anslutningssträng för resursen från en miljövariabel med namnet COMMUNICATION_SERVICES_CONNECTION_STRING. Lär dig hur du hanterar resursens anslutningssträng.

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

Om du vill autentisera med Azure Active Directory installerar du bibliotekspaketet Azure.Identity för .NET med hjälp dotnet add package av kommandot .

dotnet add package Azure.Identity

Öppna Program.cs i en textredigerare och ersätt metodens Main brödtext med kod för att initiera en EmailClient med DefaultAzureCredential. Azure Identity SDK läser värden från tre miljövariabler vid körning för att autentisera programmet. Lär dig hur du skapar ett Azure Active Directory-registrerat program och anger miljövariablerna.

// 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-postklienter kan också autentiseras med hjälp av en AzureKeyCredential. key Både och endpoint kan grundas på fönstret "Nycklar" under "Inställningar" i din Communication Services-resurs.

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

var emailClient = new EmailClient(endpoint, key);

Skicka e-postasynkronisering och avsökning för e-postsändningsstatus

När du anropar SendAsync med Azure.WaitUntil.Started returnerar metoden tillbaka när åtgärden har startats. Metoden returnerar Objektet EmailSendOperation. Du kan anropa metoden UpdateStatusAsync för att uppdatera e-poståtgärdens status.

Det returnerade Objektet EmailSendOperation innehåller ett EmailSendStatus-objekt som innehåller:

• Aktuell status för åtgärden Skicka e-post.
• Ett felobjekt med felinformation om den aktuella statusen är i ett feltillstånd.

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

Kör programmet från programkatalogen dotnet run med kommandot .

dotnet run

Exempelkod

Du kan ladda ned exempelappen från GitHub

Felsökning

E-postleverans

Om du vill felsöka problem som rör e-postleverans kan du få status för e-postleveransen för att samla in leveransinformation.

Viktigt!

Det lyckade resultatet som returneras av avsökningen för sändningsåtgärdens status verifierar bara det faktum att e-postmeddelandet har skickats ut för leverans. Om du vill få ytterligare information om statusen för leveransen på mottagarsidan måste du referera till hur du hanterar e-posthändelser.

Begränsning av e-post

Om du ser att programmet hänger kan det bero på att e-postsändningen begränsas. Du kan hantera detta genom loggning eller genom att implementera en anpassad princip.

Kommentar

Den här sandbox-installationen hjälper utvecklare att börja skapa programmet. Du kan gradvis begära att öka sändningsvolymen när programmet är redo att gå live. Skicka en supportbegäran för att höja den önskade sändningsgränsen om du behöver skicka en mängd meddelanden som överskrider hastighetsgränserna.

Rensa Azure Communication Service-resurser

Om du vill rensa och ta bort en Communication Services-prenumeration kan du ta bort resursen eller resursgruppen. Om du tar bort resursgruppen tas även alla andra resurser som är associerade med den bort. Läs mer om att rensa resurser.

Nästa steg

I den här snabbstarten lärde du dig att manuellt söka efter status när du skickar e-post med Hjälp av Azure Communication Services.

Du kanske också vill:

• Lär dig hur du skickar e-post till flera mottagare
• Läs mer om att skicka e-post med bifogade filer
• Bekanta dig med e-postklientbiblioteket