快速入門：如何使用 Azure 通訊服務傳送電子郵件

  • 發行項

注意

請透過進行這份簡短的調查，與我們分享您對 Azure 通訊服務 的看法和意見反應。

在本快速入門中，您將瞭解如何使用我們的電子郵件 SDK 來傳送電子郵件。

使用通訊服務嘗試傳送電子郵件訊息，開始使用 Azure 通訊服務。

必要條件

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

使用 Try Email 傳送電子郵件

嘗試電子郵件可協助您使用 Azure 通訊服務 開始傳送電子郵件給所需的收件者，以及驗證應用程式傳送電子郵件的設定。 它也有助於使用您慣用的語言選擇的代碼段，快速啟動電子郵件通知開發。

若要將郵件傳送給收件者，以及指定郵件主旨和本文，

  1. 從已布建 Azure 通訊服務資源的概觀頁面，按兩下 [電子郵件] 下方左側導覽面板中的 [ 試用電子郵件 ]。

    Screenshot that shows the left navigation panel for Try Email.

  2. 從下拉式清單中選取其中一個已驗證的網域。

    Screenshot that shows the verfied domain from drop-down.

  3. 撰寫要傳送的電子郵件

    • 輸入收件者電子郵件位址
    • 輸入主旨
    • 撰寫電子郵件本文

    Screenshot that shows how to filter and select one of the verified email domains to connect.

  4. 點選 [傳送]

    Screenshot that shows one of the verified email domains is now connected.

  5. 已成功傳送電子郵件。

    Screenshot that shows successful email send.

  6. 您現在可以複製範例代碼段來傳送電子郵件，以在範例專案中用來傳送通知。

    • 選取您選擇的語言

    • 按兩下 [插入我的 連線

    • 點選 [複製]

      Screenshot that shows code snippet to send email.

  7. 電子郵件代碼段現在已準備好在您的通知專案中使用。

使用 Azure CLI 通訊延伸模組來傳送電子郵件訊息，開始使用 Azure 通訊服務。

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

必要條件

先決條件檢查

  • 在終端機或命令視窗中，執行 az --version 命令來檢查是否已安裝 Azure CLI 和通訊延伸模組。
  • 若要檢視使用電子郵件通訊服務資源驗證的網域，請登入 Azure 入口網站。 找出您的電子郵件通訊服務資源，然後從左側瀏覽窗格開啟 [ 布建網域] 索引 卷標。

設定

新增擴充功能

使用 az extension 命令新增 Azure CLI 的 Azure 通訊服務 擴充功能。

az extension add --name communication

登入 Azure CLI

您必須登入 Azure CLI。 您可以從終端機登入 az login ，並提供您的認證。

將 連接字串 儲存在環境變數中

您可以將環境變數設定AZURE_COMMUNICATION_CONNECTION_STRING為使用 Azure CLI 金鑰作業，而不需要使用 --connection_string 傳入 連接字串。 若要設定環境變數，請開啟控制台視窗，然後從下列索引標籤中選取您的作業系統。 將 <connectionString> 用實際的連接字串取代。

setx AZURE_COMMUNICATION_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 執行輪詢，並傳回電子郵件傳遞的狀態。 狀態可能是下列任何一項：

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

選擇性參數

Azure CLI 提供下列選擇性參數。

  • --html 可以用於 HTML 電子郵件本文， --text 而不是 。

  • --importance 會設定電子郵件的重要性類型。 已知值為：高、標準及低。 預設值為一般。

  • --to 會設定電子郵件收件者的清單。

  • --cc 會設定副本電子郵件位址。

  • --bcc 會設定盲目碳複製電子郵件位址。

  • --reply-to 會設定回復電子郵件位址。

  • --disable-tracking 指出是否應針對此要求停用用戶參與追蹤。

  • --attachments 會設定電子郵件附件的清單。

  • --attachment-types 會以相同的附件順序設定電子郵件附件類型清單。

此外，您可以使用收件者清單搭配 --cc 和 --bcc 類似 --to。 或中至少必須有一個收件者 --to--cc--bcc。

使用通訊服務 C# 電子郵件用戶端連結庫來傳送電子郵件訊息，開始使用 Azure 通訊服務。

提示

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

瞭解電子郵件物件模型

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

名稱 描述
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 帳戶中會產生幾美分或更少成本。

注意

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

先決條件檢查

  • 在終端機或命令視窗中，執行 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);

基本電子郵件傳送

建構您的電子郵件訊息

若要傳送電子郵件訊息，您需要：

  • 定義電子郵件主旨和本文。
  • 定義您的寄件者位址。 使用寄件者資訊建構您的電子郵件訊息，以您從已驗證的網域取得MailFrom位址。
  • 定義收件者位址。
  • 呼叫 SendAsync 方法。 在 Program.cs 中，將此程式代碼新增至 方法的Main結尾：

以您的網域詳細數據取代 ，並視需要修改內容、收件者詳細數據


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

傳送並取得電子郵件傳送狀態

若要傳送電子郵件訊息，您需要：

  • 呼叫 SendAsync 方法，以異步操作方式傳送電子郵件要求。 如果您的方法應該等到服務上長時間執行的作業完成，請使用 Azure.WaitUntil.Completed 呼叫 。 如果您的方法在啟動作業之後應該傳回 ，請使用 Azure.WaitUntil.Started 呼叫 。
  • SendAsync 方法會傳回 EmailSendOperation，如果電子郵件傳回傳遞時會傳回 “Succeeded” EmailSendStatus，否則會擲回例外狀況。 在 Program.cs 中，將此程式代碼新增至 方法的Main結尾：
try
{
    Console.WriteLine("Sending email...");
    EmailSendOperation emailSendOperation = await emailClient.SendAsync(
        Azure.WaitUntil.Completed,
        sender,
        recipient,
        subject,
        htmlContent);
    EmailSendResult statusMonitor = emailSendOperation.Value;
    
    Console.WriteLine($"Email Sent. Status = {emailSendOperation.Value.Status}");

    /// 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}");
}
catch (RequestFailedException ex)
{
    /// OperationID is contained in the exception message and can be used for troubleshooting purposes
    Console.WriteLine($"Email send operation failed with error code: {ex.ErrorCode}, message: {ex.Message}");
}

取得電子郵件傳遞狀態

EmailSendOperation 只會傳回電子郵件作業狀態。 若要取得實際的電子郵件傳遞狀態，您可以訂閱 「EmailDeliveryReportReceived」事件，該事件會在電子郵件傳遞完成時產生。 事件會傳回下列傳遞狀態：

  • 交付。
  • 失敗。
  • 隔離。

如需詳細資訊，請參閱 處理電子郵件事件 。

您現在可以訂閱電子郵件作業記錄，以提供從電子郵件服務傳送之郵件傳遞計量的相關信息。

  • 電子郵件傳送郵件作業記錄 - 提供有關電子郵件服務傳送郵件要求的詳細資訊。
  • 電子郵件狀態更新作業記錄 - 提供與電子郵件服務傳送郵件要求相關的郵件和收件者層級傳遞狀態更新。

存取電子郵件通訊服務的記錄。

執行程式碼

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

dotnet run

範例指令碼

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

使用通訊服務 JS 電子郵件用戶端連結庫來傳送電子郵件訊息，開始使用 Azure 通訊服務。

提示

直接跳到 GitHub 上的基本電子郵件傳送和進階電子郵件傳送範例程式代碼，以使用 Azure 通訊服務 啟動您的電子郵件傳送體驗。

瞭解電子郵件物件模型

下列類別和介面會處理適用於 JavaScript Azure 通訊服務 Email Client 連結庫的一些主要功能。

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

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

狀態名稱 描述
isStarted 如果電子郵件傳送作業目前正在進行中且正在處理，則傳回 true。
isCompleted 如果電子郵件傳送作業已完成且電子郵件無法傳遞，則會傳回 true。 您可以透過 Azure 監視器或透過 Azure 事件方格 取得此階段以外的電子郵件傳遞的任何詳細狀態。 瞭解如何訂閱電子郵件事件
result 如果電子郵件傳送作業已結束，則存在的屬性。
error 如果電子郵件傳送作業未成功且發生錯誤，則存在的屬性。 未傳送電子郵件。 結果包含錯誤物件，其中包含失敗原因的詳細數據。

必要條件

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

注意

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

先決條件檢查

  • 在終端機或命令視窗中，執行 node --version 以檢查是否已安裝Node.js。
  • 若要檢視使用電子郵件通訊服務資源驗證的網域，請登入 Azure 入口網站，找出您的電子郵件通訊服務資源，然後從左側瀏覽窗格開啟 [布建網域] 索引卷標。

設定應用程式環境

建立新的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」。 下一節示範如何將本快速入門的原始程式碼新增至新建立的檔案。

Install the package

npm install使用 命令來安裝適用於 JavaScript 的 Azure 通訊服務 電子郵件用戶端連結庫。

npm install @azure/communication-email --save

選項--save會將連結庫列為package.json檔案中的相依性。

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

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

從用戶端連結庫匯入 EmailClient，並使用您的 連接字串 加以具現化。

下列程式代碼會使用 dotenv 套件，從名為 COMMUNICATION_SERVICES_CONNECTION_STRING 的環境變數擷取資源的 連接字串。 npm install使用 命令來安裝 dotenv 套件。 瞭解如何管理資源的 連接字串。

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 下載範例應用程式

使用通訊服務 Java 電子郵件 SDK 來傳送電子郵件訊息，開始使用 Azure 通訊服務。

提示

透過直接跳至 GitHub 上的基本電子郵件傳送和進階電子郵件傳送範例程式代碼，即可使用 Azure 通訊服務 來啟動電子郵件傳送體驗。

瞭解電子郵件物件模型

下列類別和介面會處理 Azure 通訊服務 Email SDK for Python 的一些主要功能。

名稱 描述
EmailAddress 這個類別包含電子郵件地址和顯示名稱的選項。
EmailAttachment 此介面會藉由接受唯一標識碼、電子郵件附件MIME類型字串和內容位元組字串，來建立電子郵件附件。
EmailClient 所有電子郵件功能都需要這個類別。 您可以使用 連接字串 將其具現化，並用它來傳送電子郵件訊息。
EmailMessage 這個類別結合了發件者、內容和收件者。 您也可以選擇性地新增自訂標頭、附件和回覆電子郵件位址。
EmailSendResult 這個類別會保存電子郵件傳送作業的結果。 它有作業標識碼、作業狀態和錯誤物件（適用時）。
EmailSendStatus 這個類別代表電子郵件傳送作業的狀態集。

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

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

必要條件

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

注意

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

先決條件檢查

  • 在終端機或命令視窗中，執行 mvn -v 以檢查是否已安裝 Maven。
  • 若要檢視使用電子郵件通訊服務資源驗證的網域，請登入 Azure 入口網站。 找出您的電子郵件通訊服務資源，然後從左側瀏覽窗格開啟 [ 布建網域] 索引 卷標。

設定應用程式環境

若要設定傳送電子郵件的環境，請執行下列各節中的步驟。

建立新的 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 檔案是專案的 Project 物件模型 （POM）。

Install the package

在 文本編輯器中開啟pom.xml 檔案。 將下列相依性元素加入至相依性群組。

<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 、新增匯入指示詞，以及移除 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.PollResponse;
import com.azure.core.util.polling.SyncPoller;

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

為了簡單起見，本快速入門會使用 連接字串，但在生產環境中，我們建議使用服務主體。

基本電子郵件傳送

若要傳送電子郵件訊息，請從EmailClient呼叫 函beginSend式。 這個方法會傳迴輪詢器，可用來檢查作業的狀態，並在結果完成後擷取結果。 請注意，在呼叫 方法或等候輪詢程式完成之前 poll ，不會傳送電子郵件的初始要求。

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.");

try
{
    SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null);

    PollResponse<EmailSendResult> pollResponse = null;

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

    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());
}

在程式代碼中進行這些取代：

  • 將取代 <emailalias@emaildomain.com> 為您想要傳送訊息的電子郵件位址。
  • 將取代 <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> 為您已驗證網域的 MailFrom 位址。

執行程式碼

  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 下載範例應用程式

使用通訊服務 Python 電子郵件 SDK 傳送電子郵件訊息，開始使用 Azure 通訊服務。

提示

直接跳到 GitHub 上的基本電子郵件傳送和進階電子郵件傳送範例程式代碼，以使用 Azure 通訊服務 來啟動電子郵件傳送體驗。

瞭解電子郵件物件模型

下列 JSON 訊息範本和回應物件示範適用於 Python 的 Azure 通訊服務 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下表會進一步說明這些值。

狀態名稱 描述
進行中 電子郵件傳送作業目前正在進行中並正在處理。
已成功 電子郵件傳送作業已完成，且電子郵件無法傳遞。 您可以透過 Azure 監視器或透過 Azure 事件方格 取得此階段以外的電子郵件傳遞的任何詳細狀態。 瞭解如何訂閱電子郵件事件
失敗 電子郵件傳送作業未成功，併發生錯誤。 未傳送電子郵件。 結果包含錯誤物件，其中包含失敗原因的詳細數據。

必要條件

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

注意

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

先決條件檢查

  • 在終端機或命令視窗中，執行 python --version 命令來檢查是否已安裝 Python。
  • 若要檢視使用電子郵件通訊服務資源驗證的網域，請登入 Azure 入口網站。 找出您的電子郵件通訊服務資源，然後從左側瀏覽窗格開啟 [ 布建網域] 索引 卷標。

設定應用程式環境

若要設定傳送電子郵件的環境，請執行下列各節中的步驟。

建立新的 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 檔案。

Install the package

在應用程式目錄中，請使用下列命令安裝 Azure 通訊服務 Email SDK for Python 套件。

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 帳戶。

  • 作用中 Azure 通訊服務 資源，或建立通訊服務資源。

  • 作用中的 Azure Logic Apps 資源（邏輯應用程式）和工作流程，或使用您想要使用的觸發程式建立新的邏輯應用程式資源和工作流程。 目前，Azure 通訊服務 電子郵件連接器只提供動作，因此您的邏輯應用程式工作流程至少需要觸發程式。 您可以建立 取用 或 標準 邏輯應用程式資源。

  • Azure 通訊服務 具有已設定網域或自定義網域的電子郵件資源。

  • 與 Azure 電子郵件網域連線 Azure 通訊服務 資源。

傳送電子郵件

若要使用 Azure 通訊服務 電子郵件連接器將新步驟新增至您的工作流程，請遵循下列步驟：

  1. 在設計工具中，開啟邏輯應用程式工作流程。

    耗用

    1. 在您要新增動作的步驟下，選取 [ 新增步驟]。 或者，若要在步驟之間新增動作，請將指標移至這些步驟之間的箭號上方，選取加號 （+），然後選取 [ 新增動作]。

    2. 在 [ 選擇作業 搜尋] 方塊底下，選取 [ 標準]。 在搜尋方塊中，輸入 通訊服務電子郵件。

    3. 從動作清單中，選取 [ 傳送電子郵件]。

      Screenshot that shows the Azure Communication Services Email connector Send email action.

    標準

    1. 在您要新增動作的步驟下，選取加號 （+）。 或者，若要在步驟之間新增動作，請將指標移至這些步驟之間的箭號上方，選取加號 （+），然後選取 [ 新增動作]。

    2. 在 [ 選擇作業 搜尋] 方塊底下，選取 [Azure]。 在搜尋方塊中，輸入 通訊服務電子郵件。

    3. 從動作清單中，選取 [ 傳送電子郵件]。

  2. 提供連線的名稱。

  3. 輸入 Azure 通訊服務資源的 連接字串。 若要尋找此字串，請遵循下列步驟：

    1. 在 Azure 入口網站 中，開啟您的 Azure 通訊服務資源。

    2. 在資源功能表上，選取 [設定] 底下的 [金鑰]，然後複製 連接字串。

      Screenshot that shows the Azure Communication Services Connection String.

  4. 完成時，選取建立。

  5. 在 [來源] 欄位中，使用您在必要條件中設定的電子郵件位址。 輸入 [到]、[主旨] 和 [本文] 欄位的值，例如：

    Screenshot that shows the Azure Communication Services Email connector Send email action input.

  6. 儲存您的工作流程您 在設計師工具列上選取儲存。

測試工作流程

根據您是否有取用或標準工作流程，手動啟動您的工作流程：

  • 取用：在設計工具工具列上，選取 [執行觸發程序>執行]。
  • 標準：在工作流程功能表上，選取 [ 概觀]。 在工具列上，選取 [執行觸發程序>執行]。

工作流程會建立使用者、發出該使用者的存取令牌，然後移除和刪除使用者。 您可以在工作流程順利執行之後檢查這些動作的輸出。

您應該指定的位址收到電子郵件。 此外，您可以使用 [ 取得電子郵件訊息狀態 ] 動作來檢查透過 [傳送電子郵件 ] 動作傳送的電子郵件狀態。 如需更多動作，請檢閱 Azure 通訊服務 電子郵件連接器參考檔。

清除工作流程資源

若要清除邏輯應用程式資源、工作流程和相關資源，請檢閱 如何清除取用邏輯應用程式資源 ，或 如何清除標準邏輯應用程序資源。

疑難排解

電子郵件傳遞

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

重要

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

電子郵件節流

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

注意

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

清除 Azure 通訊服務資源

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

下一步

在本快速入門中，您已瞭解如何使用 Azure 通訊服務 傳送電子郵件。 您可能也想要：