次の方法で共有


クイック スタート: Azure Communication Services を使用して電子メールを送信する方法

Note

こちらの短いアンケートに答えて、Azure Communication Services に関するご意見やフィードバックをお寄せください。

このクイック スタートでは、電子メール SDK を使用して電子メールを送信する方法について説明します。

Communication Services Try Email を使用して電子メール メッセージを送信することによって、Azure Communication Services の使用を開始します。

前提条件

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

Try Email を使用した電子メールの送信

Try Email は、Azure Communication Services を使って目的の受信者へのメール送信を始めたり、アプリケーションでのメール送信の構成を確認したりするのに役立ちます。 また、好みの言語のコード スニペットを使用して電子メール通知の開発を迅速に開始するのにも役立ちます。

受信者にメッセージを送信し、メッセージの件名と本文を指定するには、

  1. プロビジョニングされた Azure Communication Service リソースの概要ページで、左側のナビゲーション パネルの[メール] の下にある [Try Email](メールを試す) をクリックします。

    Try Email の左ナビゲーション パネルを示すスクリーンショット。

  2. ドロップダウンから検証済みドメインのいずれかを選択します。

    ドロップダウンの検証済みドメインを示すスクリーンショット。

  3. 送信する電子メールを作成する

    • 受信者の電子メール アドレスを入力する
    • 件名を入力する
    • 電子メールの本文を作成する

    接続する確認済みメール ドメインの 1 つをフィルター処理して選択する方法を示すスクリーンショット。

  4. [送信] をクリックする

    確認済みのメール ドメインのいずれかが接続されたことを示すスクリーンショット。

  5. 電子メールが正常に送信されました。

    電子メール送信の成功を示すスクリーンショット。

  6. サンプル プロジェクトで通知の送信に使用する電子メールを送信するサンプル コード スニペット をコピーすることもできます。

    • 任意の言語を選択する

    • [接続の挿入] をクリックする

    • [コピー] をクリックする

      電子メールを送信するコード スニペットを示すスクリーンショット。

  7. 電子メール コード スニペットを通知プロジェクトで使用する準備ができました。

Azure CLI 通信拡張機能を使用して電子メール メッセージを送信することによって、Azure Communication Services の使用を開始します。

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

前提条件

前提条件のチェック

  • ターミナルまたはコマンド ウィンドウで、az --version コマンドを実行して、Azure CLI と通信拡張機能がインストールされていることを確認します。
  • メール通信サービス リソースによって確認されたドメインを表示するには、Azure portal にサインインします。 メール通信サービス リソースを見つけ、左側のナビゲーション ウィンドウから [Provision domains](ドメインのプロビジョニング) タブを開きます。

設定

拡張機能の追加

az extension コマンドを使用して、Azure CLI の Azure Communication Services 拡張機能を追加します。

az extension add --name communication

Azure CLI へのサインイン

Azure CLI にサインインする必要があります。 ターミナルから az login コマンドを実行し、資格情報を入力してサインインできます。

環境変数に接続文字列を格納する

AZURE_COMMUNICATION_CONNECTION_STRING 環境変数を構成して Azure CLI のキー操作を使用できます。このとき、--connection_string を使用して接続文字列を渡す必要はありません。 環境変数を構成するには、コンソール ウィンドウを開き、以下のタブからお使いのオペレーティン グシステムを選択します。 <connectionString> は、実際の接続文字列に置き換えてください。

Note

運用環境については、暗号化されていない環境変数として接続文字列を格納しないでください。 これはテスト目的のみを意図しています。 運用環境については、新しい接続文字列を生成してください。 接続文字列を暗号化し、定期的に変更することをお勧めします。

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

実行中のプログラムのうち、環境変数の読み取りを必要とするプログラム (コンソール ウィンドウを含む) については、環境変数を追加した後で再起動が必要となる場合があります。 たとえば、Visual Studio をエディターとして使用している場合、サンプルを実行する前に Visual Studio を再起動します。

電子メール メッセージを送信する

az communication email send
	--connection-string "yourConnectionString"
	--sender "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>"
	--to "<emailalias@emaildomain.com>"
	--subject "Welcome to Azure Communication Services Email" --text "This email message is sent from Azure Communication Services Email using Azure CLI." 

コードを次のように置き換えます。

  • <yourConnectionString> を対象の接続文字列に置き換えてください。
  • <emailalias@emaildomain.com> を、メッセージの送信先メール アドレスに置き換えます。
  • <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> を、確認済みドメインの MailFrom アドレスに置き換えます。

上記のコマンドは messageId に対するポーリングも実行し、メール配信の状態が返されます。 状態は、次のいずれかになります。

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

省略可能なパラメーター

Azure CLI では、次の省略可能なパラメーターを使用できます。

  • --html は、HTML 電子メール本文で --text の代わりに使用できます。

  • --importance は、電子メールの重要度の種類を設定します。 既知の値は、high、normal、および low です。 既定値は normal です。

  • --to は、メール受信者の一覧を設定します。

  • --cc は、カーボン コピーのメール アドレスを設定します。

  • --bcc は、ブラインド カーボン コピーのメール アドレスを設定します。

  • --reply-to は、Reply-To メール アドレスを設定します。

  • --disable-tracking は、この要求に対してユーザー エンゲージメントの追跡を無効にする必要があるかどうかを示します。

  • --attachments は、電子メールの添付ファイルの一覧を設定します。

  • --attachment-types は、電子メールの添付ファイルの種類の一覧を、添付ファイルと同じ順序で設定します。

また --to と同様に、--cc--bcc でも受信者の一覧を使用できます。 --to--cc、または --bcc では、少なくとも 1 人の受信者が必要です。

Communication Services の C# Email クライアント ライブラリを使用して電子メール メッセージを送信することによって、Azure Communication Services の使用を開始します。

ヒント

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 アカウントでわずかな (数セント未満の) コストが発生します。

注意

また、独自の検証済みドメインからメールを送信することもできます。 メール通信サービスに 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);

Note

手動ポーリング (非同期状態ポーリングでメールを送信) を使用してメールを送信することが推奨されます。

基本的なメール送信

メール メッセージを作成する

メール メッセージを送信するには、次を行う必要があります。

  • メールの件名と本文を定義します。
  • 送信者アドレスを定義します。 確認済みのドメインから MailFrom アドレスを取得する送信者情報を使用して電子メール メッセージを作成します。
  • 受信者のアドレスを定義します。
  • SendAsync メソッドを呼び出します。 Program.csMain メソッドの末尾に次のコードを追加します。

ドメインの詳細に置き換え、必要に応じてコンテンツ、受信者の詳細を変更します


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

メール送信状態を送信して取得する

Azure.WaitUntil.Started を指定して SendAsync を呼び出すと、メソッドは操作の開始後に戻ります。 このメソッドから EmailSendOperation オブジェクトが返されます。 UpdateStatusAsync メソッドを呼び出して、メール操作状態を更新できます。

返された EmailSendOperation オブジェクトには EmailSendStatus オブジェクトが含まれ、このオブジェクトには次の内容が含まれています。

  • メール送信操作の現在の状態。
  • 現在の状態が失敗状態である場合は、失敗の詳細を含むエラー オブジェクト。

/// 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 からダウンロードできます

Communication Services の JS Email クライアント ライブラリを使用して電子メール メッセージを送信することによって、Azure Communication Services の使用を開始します。

ヒント

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

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

JavaScript 用 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 オブジェクトの一覧を保持します。
EmailSendResult このクラスは、メール送信操作の結果を保持します。 これには、操作 ID、操作の状態、エラー オブジェクト (該当する場合) が含まれます。
EmailSendStatus このクラスは、メール送信操作の一連の状態を表します。

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

状態の名前 説明
isStarted メール送信操作が現在進行中であり、処理中である場合に、true を返します。
isCompleted メール送信操作がエラーなしで完了し、メールが配信中の場合に、true を返します。 このステージを過ぎたメール配信に関する詳細な状態はすべて、Azure Monitor または Azure Event Grid を使用して取得できます。 メール イベントに登録する方法を確認してください
結果 メール送信操作が終了した場合に存在するプロパティ。
error メール送信操作が成功せず、エラーが発生した場合に存在するプロパティ。 メールは送信されませんでした。 結果には、失敗の理由の詳細を記したエラー オブジェクトが含まれます。

前提条件

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

注意

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

前提条件のチェック

  • ターミナルまたはコマンド ウィンドウで node --version を実行して、Node.js がインストールされていることを確認します。
  • Email Communication Services リソースにより検証済みのドメインを表示するには、Azure portal にサインインし、Email Communication Services リソースを見つけて、左側のナビゲーション ペインから [Provision domains] (ドメインのプロビジョニング) タブを開きます。

アプリケーション環境の設定

新しい Node.js アプリケーションを作成する

まず、ターミナルまたはコマンド ウィンドウを開き、アプリ用の新しいディレクトリを作成して、そこに移動します。

mkdir email-quickstart && cd email-quickstart

既定の設定で npm init -y を実行して、package.json ファイルを作成します。

npm init -y

テキスト エディターを使用して、プロジェクトのルート ディレクトリに send-email.js というファイルを作成します。 package.json の "main" プロパティを "send-email.js" に変更します。 次のセクションでは、新しく作成したファイルにこのクイックスタートのソース コードを追加する方法について説明します。

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

npm install コマンドを使用して、JavaScript 用の Azure Communication Services Email クライアント ライブラリをインストールします。

npm install @azure/communication-email --save

--save オプションを使用すると、package.json ファイル内の依存関係としてライブラリが表示されます。

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

電子メール クライアントの認証には、いくつかの異なるオプションがあります。

クライアント ライブラリから EmailClient をインポートし、接続文字列を使用してインスタンス化します。

次のコードは、dotenv パッケージを使用して、COMMUNICATION_SERVICES_CONNECTION_STRING という名前の環境変数からリソースの接続文字列を取得します。 dotenv パッケージをインストールするには、npm install コマンドを使います。 リソースの接続文字列を管理する方法について確認してください。

npm install dotenv

次のコードを send-email.js に追加します。

const { EmailClient } = require("@azure/communication-email");
require("dotenv").config();

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];
const emailClient = new EmailClient(connectionString);

このクイックスタートでは、簡潔にするために接続文字列を使用していますが、運用環境では、サービス プリンシパルの使用をお勧めします。

基本的なメール送信

電子メール メッセージを送信する

メール メッセージを送信するには、EmailClient から beginSend 関数を呼び出します。 このメソッドによりポーラーが返され、このポーラーによって操作のステータスが調べられ、終了すると結果が取得されます。


async function main() {
  const POLLER_WAIT_TIME = 10
  try {
    const message = {
      senderAddress: "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>",
      content: {
        subject: "Welcome to Azure Communication Services Email",
        plainText: "This email message is sent from Azure Communication Services Email using the JavaScript SDK.",
      },
      recipients: {
        to: [
          {
            address: "<emailalias@emaildomain.com>",
            displayName: "Customer Name",
          },
        ],
      },
    };

    const poller = await emailClient.beginSend(message);

    if (!poller.getOperationState().isStarted) {
      throw "Poller was not started."
    }

    let timeElapsed = 0;
    while(!poller.isDone()) {
      poller.poll();
      console.log("Email send polling in progress");

      await new Promise(resolve => setTimeout(resolve, POLLER_WAIT_TIME * 1000));
      timeElapsed += 10;

      if(timeElapsed > 18 * POLLER_WAIT_TIME) {
        throw "Polling timed out.";
      }
    }

    if(poller.getResult().status === KnownEmailSendStatus.Succeeded) {
      console.log(`Successfully sent the email (operation id: ${poller.getResult().id})`);
    }
    else {
      throw poller.getResult().error;
    }
  } catch (e) {
    console.log(e);
  }
}

main();

コードを次のように置き換えます。

  • <emailalias@emaildomain.com> を、メッセージの送信先メール アドレスに置き換えます。
  • <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> を、確認済みドメインの MailFrom アドレスに置き換えます。

コードの実行

node コマンドを使用して、send-email.js ファイルに追加したコードを実行します。

node ./send-email.js

サンプル コード

サンプル アプリは GitHub からダウンロードできます

Communication Services Java Email SDK を使用してメール メッセージを送信することによって、Azure Communication Services の使用を開始します。

ヒント

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

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

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

名前 説明
EmailAddress このクラスには、メール アドレスと表示名のオプションが含まれています。
EmailAttachment このインターフェイスは、一意の ID、メール添付ファイルの MIME の種類の文字列、コンテンツのバイト数の文字列、添付ファイルをインライン添付ファイルとして定義するオプションのコンテンツ ID を受け入れて、メールの添付ファイルを作成します。
EmailClient このクラスは、すべてのメール機能に必要となります。 接続文字列を使用してこれをインスタンス化し、それを使用して電子メール メッセージを送信します。
EmailMessage このクラスは、送信者、コンテンツ、受信者を結合します。 カスタム ヘッダー、添付ファイル、および返信先のメール アドレスも必要に応じて追加できます。
EmailSendResult このクラスは、メール送信操作の結果を保持します。 これには、操作 ID、操作の状態、エラー オブジェクト (該当する場合) が含まれます。
EmailSendStatus このクラスは、メール送信操作の一連の状態を表します。

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

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

前提条件

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

Note

独自の検証済みドメインからメールを送信することもできます。メール通信サービスにカスタムの検証済みドメインを追加します。

前提条件のチェック

  • ターミナルまたはコマンド ウィンドウで mvn -v を実行して、Maven がインストールされていることを確認します。
  • メール通信サービス リソースによって確認されたドメインを表示するには、Azure portal にサインインします。 メール通信サービス リソースを見つけ、左側のナビゲーション ウィンドウから [Provision domains](ドメインのプロビジョニング) タブを開きます。

アプリケーション環境の設定

メールを送信するための環境を設定するには、次のセクションの手順を実行します。

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

ターミナルまたはコマンド ウィンドウを開き、Java アプリケーションを作成するディレクトリに移動します。 次のコマンドを実行して、maven-archetype-quickstart テンプレートから Java プロジェクトを生成します。

mvn archetype:generate -DarchetypeArtifactId="maven-archetype-quickstart" -DarchetypeGroupId="org.apache.maven.archetypes" -DarchetypeVersion="1.4" -DgroupId="com.communication.quickstart" -DartifactId="communication-quickstart"

generate 目標により、artifactId 値と同じ名前のディレクトリが作成されます。 このディレクトリの下の src/main/java ディレクトリにはプロジェクトのソース コードが、src/test/java ディレクトリにはテスト ソースがそれぞれ含まれており、pom.xml ファイルはプロジェクトのプロジェクト オブジェクト モデル (POM) です。

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

テキスト エディターで pom.xml ファイルを開きます。 依存関係のグループに、次の dependency 要素を追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-email</artifactId>
    <version>1.0.0-beta.2</version>
</dependency>

アプリのフレームワークを設定する

テキスト エディターで /src/main/java/com/communication/quickstart/App.java を開き、import ディレクティブを追加して、System.out.println("Hello world!"); ステートメントを削除します。

package com.communication.quickstart;

import com.azure.communication.email.models.*;
import com.azure.communication.email.*;
import com.azure.core.util.polling.*;

public class App
{
    public static void main( String[] args )
    {
        // Quickstart code goes here.
    }
}

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

メール クライアントの認証には、いくつかのオプションを使用できます。

クライアントを認証するには、接続文字列を使用して EmailClient をインスタンス化します。 リソースの接続文字列を管理する方法について確認してください。 クライアントは、com.azure.core.http.HttpClient インターフェイスを実装する任意のカスタム HTTP クライアントを使用して初期化することもできます。

同期クライアントをインスタンス化するには、main メソッドに次のコードを追加します。

// You can get your connection string from your resource in the Azure portal.
String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";

EmailClient emailClient = new EmailClientBuilder()
    .connectionString(connectionString)
    .buildClient();

非同期クライアントをインスタンス化するには、main メソッドに次のコードを追加します。

// You can get your connection string from your resource in the Azure portal.
String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";

EmailAsyncClient emailClient = new EmailClientBuilder()
    .connectionString(connectionString)
    .buildAsyncClient();

このクイックスタートでは、簡潔にするために接続文字列を使用していますが、運用環境では、サービス プリンシパルの使用をお勧めします。

基本的なメール送信

メール メッセージは、SDK 内の EmailMessage オブジェクトを使用して作成できます。

EmailMessage message = new EmailMessage()
    .setSenderAddress("<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>")
    .setToRecipients("<emailalias@emaildomain.com>")
    .setSubject("Welcome to Azure Communication Services Email")
    .setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.");

コードを次のように置き換えます。

  • <emailalias@emaildomain.com> を、メッセージの送信先メール アドレスに置き換えます。
  • <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> を、確認済みドメインの MailFrom アドレスに置き換えます。

メール メッセージを送信するには、EmailClient から beginSend 関数を呼び出します。

同期クライアントで beginSend を呼び出すと、SyncPoller オブジェクトが返されます。これは、操作のステータスを調べ、終了時に結果を取得するために使用できます。 最初のメール送信要求は、beginSend メソッドが呼び出されるとすぐに送信されます。 メールの送信は、実行時間の長い操作です。 ポーラーの getFinalResult() メソッドは、終了状態 (SUCCESSFULLY_COMPLETED または FAILED) に達するまでのブロック操作であることに注意してください。 推奨される方法は、次のサンプルに示すように、アプリケーションのニーズに適した間隔で手動ポーリングを実行することです。

try
{
    SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null); // This will send out the initial request to send an email

    PollResponse<EmailSendResult> pollResponse = null;

    Duration timeElapsed = Duration.ofSeconds(0);
    Duration POLLER_WAIT_TIME = Duration.ofSeconds(10);

    // Polling is done manually to avoid blocking the application in case of an error
    while (pollResponse == null
            || pollResponse.getStatus() == LongRunningOperationStatus.NOT_STARTED
            || pollResponse.getStatus() == LongRunningOperationStatus.IN_PROGRESS)
    {
        pollResponse = poller.poll();
        System.out.println("Email send poller status: " + pollResponse.getStatus());

        Thread.sleep(POLLER_WAIT_TIME.toMillis());
        timeElapsed = timeElapsed.plus(POLLER_WAIT_TIME);

        if (timeElapsed.compareTo(POLLER_WAIT_TIME.multipliedBy(18)) >= 0)
        {
            throw new RuntimeException("Polling timed out.");
        }
    }

    if (poller.getFinalResult().getStatus() == EmailSendStatus.SUCCEEDED)
    {
        System.out.printf("Successfully sent the email (operation id: %s)", poller.getFinalResult().getId());
    }
    else
    {
        throw new RuntimeException(poller.getFinalResult().getError().getMessage());
    }
}
catch (Exception exception)
{
    System.out.println(exception.getMessage());
}

コードの実行

  1. pom.xml ファイルが格納されているディレクトリに移動し、mvn コマンドを使用してプロジェクトをコンパイルします。

    mvn compile
    
  2. パッケージをビルドします。

    mvn package
    
  3. 次の mvn コマンドを実行して、アプリを実行します。

    mvn exec:java -D"exec.mainClass"="com.communication.quickstart.App" -D"exec.cleanupDaemonThreads"="false"
    

サンプル コード

サンプル アプリは GitHub からダウンロードできます

Communication Services Python Email SDK を使用してメール メッセージを送信することによって、Azure Communication Services の使用を開始します。

ヒント

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

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

以下の JSON メッセージ テンプレートと応答オブジェクトには、Python 用 Azure Communication Services Email SDK の主な機能がいくつか示されています。

message = {
    "content": {
        "subject": "str",  # Subject of the email message. Required.
        "html": "str",  # Optional. Html version of the email message.
        "plainText": "str"  # Optional. Plain text version of the email
            message.
    },
    "recipients": {
        "to": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ],
        "bcc": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ],
        "cc": [
            {
                "address": "str",  # Email address. Required.
                "displayName": "str"  # Optional. Email display name.
            }
        ]
    },
    "senderAddress": "str",  # Sender email address from a verified domain. Required.
    "attachments": [
        {
            "contentInBase64": "str",  # Base64 encoded contents of the attachment. Required.
            "contentType": "str",  # MIME type of the content being attached. Required.
            "name": "str"  # Name of the attachment. Required.
        }
    ],
    "userEngagementTrackingDisabled": bool,  # Optional. Indicates whether user engagement tracking should be disabled for this request if the resource-level user engagement tracking setting was already enabled in the control plane.
    "headers": {
        "str": "str"  # Optional. Custom email headers to be passed.
    },
    "replyTo": [
        {
            "address": "str",  # Email address. Required.
            "displayName": "str"  # Optional. Email display name.
        }
    ]
}

response = {
    "id": "str",  # The unique id of the operation. Uses a UUID. Required.
    "status": "str",  # Status of operation. Required. Known values are:
        "NotStarted", "Running", "Succeeded", and "Failed".
    "error": {
        "additionalInfo": [
            {
                "info": {},  # Optional. The additional info.
                "type": "str"  # Optional. The additional info type.
            }
        ],
        "code": "str",  # Optional. The error code.
        "details": [
            ...
        ],
        "message": "str",  # Optional. The error message.
        "target": "str"  # Optional. The error target.
    }
}

response.status 値の詳細については、次の表を参照してください。

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

前提条件

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

注意

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

前提条件のチェック

  • ターミナルまたはコマンド ウィンドウで python --version コマンドを実行して、Python がインストールされていることを確認します。
  • メール通信サービス リソースによって確認されたドメインを表示するには、Azure portal にサインインします。 メール通信サービス リソースを見つけ、左側のナビゲーション ウィンドウから [Provision domains](ドメインのプロビジョニング) タブを開きます。

アプリケーション環境の設定

メールを送信するための環境を設定するには、次のセクションの手順を実行します。

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

  1. ターミナルまたはコマンド ウィンドウを開きます。 続いて、次のコマンドを使用して仮想環境を作成し、アクティブにします。 このコマンドにより、アプリの新しいディレクトリが作成されます。

    python -m venv email-quickstart
    
  2. 仮想環境のルート ディレクトリに移動し、次のコマンドを使用してアクティブにします。

    cd email-quickstart
    .\Scripts\activate
    
  3. テキスト エディターを使用して send-email.py という名前のファイルをプロジェクトのルート ディレクトリに作成し、基本的な例外処理を含むプログラムの構造を追加します。

    import os
    from azure.communication.email import EmailClient
    
    try:
        # Quickstart code goes here.
    except Exception as ex:
        print('Exception:')
        print(ex)
    

以降のセクションでは、このクイックスタートのすべてのソース コードを、作成した send-email.py ファイルに追加していきます。

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

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

pip install azure-communication-email

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

電子メール クライアントの認証には、いくつかの異なるオプションがあります。

接続文字列を使用して EmailClient をインスタンス化します。 リソースの接続文字列を管理する方法について確認してください。

# Create the EmailClient object that you use to send Email messages.
email_client = EmailClient.from_connection_string(<connection_string>)

このクイックスタートでは、簡潔にするために接続文字列を使用していますが、運用環境では、サービス プリンシパルの使用をお勧めします。

基本的なメール送信

電子メール メッセージを送信する

メール メッセージを送信するには、次を行う必要があります。

  • 次の値を使用してメッセージを作成します。
    • senderAddress: 有効な送信者のメール アドレス。メール通知サービス リソースにリンクされているドメインの概要ウィンドウの [MailFrom] フィールドにあります。
    • recipients: メール受信者のリストと、必要に応じて CC と BCC メール受信者のリストを含むオブジェクト。
    • content: メール メッセージの件名と、必要に応じてプレーンテキストまたは HTML コンテンツを含むオブジェクト。
  • 操作の結果を返す begin_send メソッドを呼び出します。
message = {
    "content": {
        "subject": "This is the subject",
        "plainText": "This is the body",
        "html": "<html><h1>This is the body</h1></html>"
    },
    "recipients": {
        "to": [
            {
                "address": "<emailalias@emaildomain.com>",
                "displayName": "Customer Name"
            }
        ]
    },
    "senderAddress": "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>"
}

poller = email_client.begin_send(message)
print("Result: " + poller.result())

コードを次のように置き換えます。

  • <emailalias@emaildomain.com> を、メッセージの送信先メール アドレスに置き換えます。
  • <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> を、確認済みドメインの MailFrom アドレスに置き換えます。

メール配信の状態を取得する

EmailClient の begin_send メソッドから返される操作状態オブジェクトにループを設定することで、メール配信状態をポーリングできます。

POLLER_WAIT_TIME = 10

try:
    email_client = EmailClient.from_connection_string(connection_string)

    poller = email_client.begin_send(message);

    time_elapsed = 0
    while not poller.done():
        print("Email send poller status: " + poller.status())

        poller.wait(POLLER_WAIT_TIME)
        time_elapsed += POLLER_WAIT_TIME

        if time_elapsed > 18 * POLLER_WAIT_TIME:
            raise RuntimeError("Polling timed out.")

    if poller.result()["status"] == "Succeeded":
        print(f"Successfully sent the email (operation id: {poller.result()['id']})")
    else:
        raise RuntimeError(str(poller.result()["error"]))

except Exception as ex:
    print(ex)

コードの実行

アプリケーション ディレクトリから python コマンドを使用してアプリケーションを実行します。

python send-email.py

サンプル コード

サンプル アプリは GitHub からダウンロードできます

前提条件

  • アクティブなサブスクリプションを含む Azure アカウント。または、アカウントを無料で作成してください。

  • アクティブな Azure Communication Services リソース。または、Communication Services リソースを作成してください。

  • アクティブな Azure Logic Apps リソース (ロジック アプリ) とワークフロー。または、新しいロジック アプリ リソースと、使用するトリガーを含むワークフローを作成します。 現在、Azure Communication Services の Email コネクタで提供されるのはアクションのみです。そのためロジック アプリ ワークフローには、少なくともトリガーが必要です。 従量課金または標準のロジック アプリ リソースを作成できます。

  • 構成済みドメインまたはカスタム ドメインを持つ Azure Communication Services Email リソース。

  • Azure Email ドメインに接続されている Azure Communication Services リソース。

電子メールの送信

Azure Communication Services Email コネクタを使用してワークフローに新しいステップを追加するには、次の手順に従います。

  1. デザイナーで、ロジック アプリ ワークフローを開きます。

    従量課金プラン

    1. 新しいアクションを追加するステップで、[新しいステップ] を選択します。 また、ステップとステップの間に新しいアクションを追加するには、それらのステップ間の矢印にポインターを合わせて、正符号 (+) を選択し、[アクションの追加] を選択します。

    2. [操作を選択してください] の検索ボックスで、[Premium] を選択します。 検索ボックスに「Azure Communication Email」と入力します。

    3. アクションの一覧から、[メールを送信する] を選択します。

      Azure Communication Services Email コネクタの [メールを送信する] アクションを示すスクリーンショット。

    Standard

    1. 新しいアクションを追加するステップで、正符号 (+) を選択します。 また、ステップとステップの間に新しいアクションを追加するには、それらのステップ間の矢印にポインターを合わせて、正符号 (+) を選択し、[アクションの追加] を選択します。

    2. [アクションの追加] 検索ボックスのランタイム ドロップダウンで [Premium] を選択します。 検索ボックスに「Azure Communication Email」と入力します。

    3. アクションの一覧から、[メールを送信する] を選択します。

  2. 接続の名前を入力します。

  3. Azure Communications Service リソースの接続文字列を入力します。 この文字列を見つけるには、次の手順に従います。

    1. Azure portal で、Azure Communication Service リソースを開きます。

    2. リソース メニューの [設定][キー] を選択し、接続文字列をコピーします。

      Azure Communication Services の [接続文字列] を示すスクリーンショット。

  4. 完了したら [作成] を選択します。

  5. [差出人] フィールドで、前提条件で構成したメール アドレスを使用します。 [宛先][件名][本文] フィールドに値を入力します。次に例を示します。

    Azure Communication Services Email コネクタの [メールを送信する] アクションの入力を示すスクリーンショット。

  6. ワークフローを保存します。 デザイナーのツール バーで、 [保存] を選択します。

ワークフローのテスト

従量課金ワークフローと標準ワークフローのどちらを使用しているかに基づいて、ワークフローを手動で開始します。

  • 従量課金: デザイナーのツール バーで、[トリガーの実行]>[実行] を選択します。
  • 標準: ワークフロー メニューで [概要] を選択します。 ツール バーで、[トリガーの実行]>[実行] を選択します。

このワークフローでは、ユーザーが作成され、そのユーザーのアクセス トークンが発行され、その後ユーザーが削除されます。 ワークフローが正常に実行された後で、これらのアクションの出力を確認できます。

指定したアドレスにメールが届きます。 また、[Get email message status] (メール メッセージの状態を取得する) アクションを使用して、[メールを送信する] アクションで送信されたメールの状態を確認できます。 その他のアクションについては、Azure Communication Services Email コネクタのリファレンス ドキュメントに関するページを参照してください。

ワークフロー リソースをクリーンアップする

ロジック アプリ リソース、ワークフロー、関連リソースのクリーンアップについては、従量課金ロジック アプリ リソースのクリーンアップ方法または Standard ロジック アプリ リソースのクリーンアップ方法に関する記事をご覧ください。

トラブルシューティング

電子メール配信

電子メール配信に関連する問題をトラブルシューティングするために、電子メール配信の状態を取得して配信の詳細を取得できます。

重要

送信操作の状態のポーリングによって返された成功の結果は、電子メールが正常に配信されたという事実のみを検証するものです。 受信者側の配信の状態について追加情報を得るには、電子メール イベントの処理方法を参照する必要があります。

電子メール調整

アプリケーションがハングしている場合は、メール送信が調整されていることが原因である可能性があります。 これを処理するには、ログ記録を使用するか、カスタム ポリシーを実装します

注意

このサンドボックスの設定は、開発者によるアプリケーションのビルド開始を支援するためのものです。 アプリケーションを公開する準備ができたら、次第に送信量を増やすことを要求できるようになります。 レート制限を超える量のメッセージを送信する必要がある場合は、必要な送信制限を引き上げるように求めるサポート リクエストを送信してください。

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

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

次の手順

このクイックスタートでは、Azure Communication Services を使用してメールを送信する方法について学習しました。 次の記事もご覧ください。