快速入門：在傳送電子郵件時手動輪詢電子郵件狀態

發行項
04/29/2024

在本快速入門中，您將了解如何使用電子郵件 SDK 在傳送電子郵件時手動輪詢電子郵件狀態。

藉由使用通訊服務 .NET 電子郵件用戶端程式庫來傳送電子郵件訊息，開始使用 Azure 通訊服務。

提示

透過直接跳至 GitHub 上的基本電子郵件傳送和進階電子郵件傳送範例程式碼，立即開始透過 Azure 通訊服務的電子郵件傳送體驗。

了解電子郵件物件模型

下列類別和介面會處理 Azure 通訊服務電子郵件用戶端程式庫的一些主要 C# 功能。

名稱	描述
EmailAddress	此類別包含電子郵件地址和顯示名稱的選項。
EmailAttachment	這個類別會藉由接受唯一標識碼、電子郵件附件 MIME類型字串、內容的二進位數據，以及選擇性內容識別碼來將其定義為內嵌附件，以建立電子郵件附件。
EmailClient	這是所有電子郵件功能所需的類別。請使用您的連接字串來對其進行具現化，並使用其來傳送電子郵件訊息。
EmailClientOptions	此類別可以新增至 EmailClient 具現化，以針對特定的 API 版本。
EmailContent	此類別含有電子郵件訊息的主旨和本文。您必須至少指定一個 PlainText 或 Html 內容
EmailCustomHeader	此類別讓使用者可以新增自訂標題的名稱和值組。您也可以使用標頭名稱 'x-priority' 或 'x-msmail-priority'，透過這些標頭指定電子郵件重要性
EmailMessage	此類別會合併傳送者、內容及收件者。您也可以選擇性地新增自訂標題、附件及回復電子郵件地址。
EmailRecipients	此類別會保留電子郵件訊息收件者的 EmailAddress 物件清單，包括 CC 與 BCC 收件者的選擇性清單。
EmailSendOperation	此類別代表非同步電子郵件傳送作業，並從電子郵件傳送 API 呼叫傳回。
EmailSendResult	此類別會保存電子郵件傳送作業的結果。具有作業識別碼、作業狀態和錯誤物件 (適用時)。

EmailSendResult 會對執行的電子郵件作業傳回下列狀態。

狀態	描述
未開始	我們目前不會從我們的服務傳送此狀態。
執行中	電子郵件傳送作業目前正在進行中並且正在進行處理。
成功	電子郵件傳送作業已完成，沒有電子郵件無法傳遞的錯誤。您可以透過 Azure 監視器或 Azure 事件方格，取得此階段以外電子郵件傳遞的任何詳細狀態。了解如何訂閱電子郵件事件
失敗	電子郵件傳送作業未成功，且發生錯誤。未傳送電子郵件。結果包含錯誤物件，其中包含失敗原因的詳細資料。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
適用於您的作業系統的最新版本 .NET Core 用戶端程式庫。
已建立 Azure 電子郵件通訊服務資源，並已準備佈建從建立電子郵件通訊資源開始著手的網域
使用電子郵件網域和連接字串進行連線的作用中通訊服務資源。將通訊資源與電子郵件資源連線來開始著手

完成本快速入門後，您的 Azure 帳戶中會產生幾美分或更少的費用。

注意

我們也可以從自己的已驗證網域傳送電子郵件。將自訂已驗證網域新增至電子郵件通訊服務。

先決條件檢查

在終端機或命令視窗中執行 dotnet 命令，確認已安裝 .NET 用戶端程式庫。
若要檢視與您電子郵件通訊服務資源相關聯的子網域，請登入 Azure 入口網站、尋找您的電子郵件通訊服務資源，然後從左側瀏覽窗格開啟 [佈建] 索引標籤。

建立新的 C# 應用程式

在主控台視窗中 (例如 cmd、PowerShell 或 Bash)，使用 dotnet new 命令建立名為 EmailQuickstart 的新主控台應用程式。此命令會建立簡單的 "Hello World" C# 專案，內含單一原始程式檔：Program.cs。

dotnet new console -o EmailQuickstart

將您的目錄變更為新建立的應用程式資料夾，然後使用 dotnet build 命令來編譯您的應用程式。

cd EmailQuickstart
dotnet build

Install the package

若您仍在應用程式目錄中，請使用 dotnet add package 命令安裝適用於 .NET 套件的 Azure 通訊服務電子郵件用戶端程式庫。

dotnet add package Azure.Communication.Email

使用驗證建立電子郵件用戶端

開啟 Program.cs，並以下列程式碼取代現有的程式碼，以新增 using 指示詞，並包含 Azure.Communication.Email 命名空間及您程式執行的起點。


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

    }
  }
}

有一些不同的選項可用來驗證電子郵件用戶端：

在文字編輯器中開啟 Program.cs，並將 Main 方法的本文取代為程式碼，以使用您的連接字串來初始化 EmailClient。以下程式碼會從名為 COMMUNICATION_SERVICES_CONNECTION_STRING 的環境變數中，擷取資源的連接字串。了解如何管理您資源的連接字串。

// 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 進行驗證，請藉由使用 dotnet add package 命令安裝適用於 .NET 的 Azure.Identity 程式庫套件。

dotnet add package Azure.Identity

在文字編輯器中開啟 Program.cs，並將 Main 方法的本文取代為程式碼，以使用 DefaultAzureCredential 來初始化 EmailClient。 Azure 身分識別 SDK 會在執行階段讀取三個環境變數中的值，以驗證應用程式。了解如何建立 Azure Active Directory 已註冊應用程式並且設定環境變數。

// 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 來驗證電子郵件用戶端。 key 和 endpoint 都可以在通訊服務資源中 [設定] 底下的 [金鑰] 窗格中找到。

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

var emailClient = new EmailClient(endpoint, key);

非同步傳送電子郵件並輪詢電子郵件傳送狀態

當您使用 Azure.WaitUntil.Started 呼叫 SendAsync 時，您的方法會在開始作業後傳回。方法會傳回 EmailSendOperation 物件。您可以呼叫 UpdateStatusAsync 方法來重新整理電子郵件作業狀態。

傳回的 EmailSendOperation 物件包含 EmailSendStatus 物件，其中包含：

電子郵件傳送作業的目前狀態。
如果目前狀態處於失敗狀態，則為包含失敗詳細資訊的錯誤物件。


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

使用 dotnet run 命令從您的應用程式目錄執行應用程式。

dotnet run

範例指令碼

您可以從 GitHub 下載範例應用程式

疑難排解

電子郵件傳遞

若要針對與電子郵件傳遞相關的問題進行疑難排解，您可以取得電子郵件傳遞的狀態以擷取傳遞的詳細資料。

重要

輪詢傳送作業狀態所傳回的成功結果只會驗證已成功傳送電子郵件以傳遞的事實。若要取得收件者端傳遞狀態的其他資訊，您必須參考如何處理電子郵件事件。

電子郵件節流

如果您看到應用程式已停止回應，可能是因為電子郵件傳送受到節流處理。您可以透過記錄或實作自訂原則來處理此作業。

注意

此沙箱設定是為了協助開發人員開始建置應用程式。一旦應用程式準備好上線，您便可以逐漸要求增加傳送量。如果您需要傳送超過比率限制的郵件訊息量，請提交支援要求來提高您想要的傳送限制量。

清除 Azure 通訊服務資源

如果您想要清除並移除通訊服務訂用帳戶，您可以刪除資源或資源群組。刪除資源群組也會刪除與其相關聯的任何其他資源。深入了解如何清除資源。

下一步

在本快速入門中，您已了解如何使用 Azure 通訊服務在傳送電子郵件時手動輪詢狀態。

您可能也會想要：

共用方式為