クイックスタート: メールの送信時にメールの状態を手動でポーリングする

[アーティクル]
07/26/2023

このクイックスタートでは、メール SDK を使用して、メールの送信時にメールの状態を手動でポーリングする方法について説明します。

Azure Communication Services の使用を開始するために、Communication Services .NET Email クライアントライブラリを使用してメールメッセージを送信します。

ヒント

GitHub の基本的な電子メールの送信と高度な電子メールの送信サンプルコードに直接スキップして、Azure Communication Services を使用した電子メール送信エクスペリエンスを開始します。

メールオブジェクトモデルについて

C# 用 Azure Communication Services Email クライアントライブラリが備える主な機能のいくつかは、以下のクラスとインターフェイスにより処理されます。

名前	説明
EmailAddress	このクラスには、メールアドレスと表示名のオプションが含まれています。
EmailAttachment	このクラスは、一意の ID、メール添付ファイルの MIME の種類の文字列、コンテンツのバイナリデータ、添付ファイルをインライン添付ファイルとして定義するオプションのコンテンツ ID を受け入れて、メールの添付ファイルを作成します。
EmailClient	このクラスは、すべてのメール機能に必要となります。接続文字列を使用してこれをインスタンス化し、それを使用して電子メールメッセージを送信します。
EmailClientOptions	このクラスを EmailClient のインスタンス化に追加して、特定の API バージョンをターゲットにすることができます。
EmailContent	このクラスには、電子メールメッセージの件名と本文が含まれています。プレーンテキストまたは Html コンテンツの少なくとも 1 つを指定する必要があります
EmailCustomHeader	このクラスにより、カスタムヘッダーの名前と値のペアを追加できます。メールの重要度は、ヘッダー名 'x-priority' または 'x-msmail-priority' を使用して、これらのヘッダーで指定することもできます
EmailMessage	このクラスは、送信者、コンテンツ、受信者を結合します。カスタムヘッダー、添付ファイル、および返信先のメールアドレスも必要に応じて追加できます。
EmailRecipients	このクラスは、CC と BCC 受信者のオプションリストなど、メールメッセージの受信者に関する EmailAddress オブジェクトの一覧を保持します。
EmailSendOperation	このクラスは、非同期のメール送信操作を表し、メール送信 API 呼び出しから返されます。
EmailSendResult	このクラスは、メール送信操作の結果を保持します。これには、操作 ID、操作の状態、エラーオブジェクト (該当する場合) が含まれます。

EmailSendResult は、実行されたメール操作について次の状態を返します。

Status	説明
NotStarted	現時点では、この状態をサービスから送信していません。
実行中	メール送信操作は現在進行中であり、処理中です。
成功	メール送信操作がエラーなしで完了し、メールは配信中です。このステージを過ぎたメール配信に関する詳細な状態はすべて、Azure Monitor または Azure Event Grid を使用して取得できます。メールイベントに登録する方法を確認してください
失敗	メール送信操作が成功せず、エラーが発生しました。メールは送信されませんでした。結果には、失敗の理由の詳細を記したエラーオブジェクトが含まれます。

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
お使いのオペレーティングシステムに対応した最新バージョンの .NET Core クライアントライブラリ。
作成され、プロビジョニングされたドメインと共に準備が整った Azure Email Communication Services リソース。電子メール通信リソースの作成に関する概要
メールドメインに接続されているアクティブな Communication Services リソースと接続文字列。電子メールリソースと通信リソースを接続して開始する

このクイックスタートを完了すると、ご利用の Azure アカウントでわずかな (数セント未満の) コストが発生します。

注意

また、独自の検証済みドメインからメールを送信することもできます。メール通信サービスに Azure マネージドドメインを追加する方法。

前提条件のチェック

ターミナルまたはコマンドウィンドウで dotnet コマンドを実行して、.NET クライアントライブラリがインストールされていることを確認します。
Email Communication Services リソースに関連付けられているサブドメインを表示するには、Azure portal にサインインし、Email Communication Services リソースを見つけて、左側のナビゲーションペインから [Provision domains] (ドメインのプロビジョニング) タブを開きます。

新しい C# アプリケーションを作成する

コンソールウィンドウ (cmd、PowerShell、Bash など) で、dotnet new コマンドを使用し、EmailQuickstart という名前で新しいコンソールアプリを作成します。このコマンドにより、1 つのソースファイルを使用する単純な "Hello World" C# プロジェクトが作成されます。Program.cs。

dotnet new console -o EmailQuickstart

新しく作成したアプリフォルダーにディレクトリを変更し、dotnet build コマンドを使用してアプリケーションをコンパイルします。

cd EmailQuickstart
dotnet build

パッケージをインストールする

まだアプリケーションディレクトリにいる間に、dotnet add package コマンドを使用して、.NET 用の Azure Communication Services Email クライアントライブラリパッケージをインストールします。

dotnet add package Azure.Communication.Email

認証を使用したメールクライアントの作成

Program.cs を開き、既存のコードを次のコードに置き換えて、Azure.Communication.Email 名前空間とプログラムの開始点を含めるための using ディレクティブを追加します。


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 ID SDK では、実行時に 3 つの環境変数から値が読み取られ、アプリケーションが認証されます。 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 の両方は、Communication Services リソースの [設定] の下にある [キー] ペインに基づいて作成できます。

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 Communication Services のリソースをクリーンアップする

Communication Services サブスクリプションをクリーンアップして解除する場合は、リソースまたはリソースグループを削除できます。リソースグループを削除すると、それに関連付けられている他のリソースも削除されます。詳細については、リソースのクリーンアップに関する記事を参照してください。

次の手順

このクイックスタートでは、Azure Communication Services を使用して電子メールを送信する際に状態を手動でポーリングする方法について説明しました。

次のことも実行できます。

次の方法で共有

クイックスタート: メールの送信時にメールの状態を手動でポーリングする

メールオブジェクトモデルについて

前提条件

前提条件のチェック

新しい C# アプリケーションを作成する

パッケージをインストールする

認証を使用したメールクライアントの作成

メールの非同期送信と、メール送信状態のポーリング

サンプルコード

トラブルシューティング

電子メール配信

電子メール調整

Azure Communication Services のリソースをクリーンアップする

次の手順

フィードバック

その他のリソース

次の方法で共有

クイック スタート: メールの送信時にメールの状態を手動でポーリングする

メール オブジェクト モデルについて

前提条件

前提条件のチェック

新しい C# アプリケーションを作成する

パッケージをインストールする

認証を使用したメール クライアントの作成

メールの非同期送信と、メール送信状態のポーリング

サンプル コード

トラブルシューティング

電子メール配信

電子メール調整

Azure Communication Services のリソースをクリーンアップする

次の手順

フィードバック

その他のリソース

クイックスタート: メールの送信時にメールの状態を手動でポーリングする

メールオブジェクトモデルについて

認証を使用したメールクライアントの作成

サンプルコード