共用方式為

使用 Azure 通訊服務傳送電子郵件

本快速入門說明如何使用我們的電子郵件 SDK 來傳送電子郵件。

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

先決條件

完成此文章可能會在您的 Azure 帳戶中產生一小筆成本，約為幾美分或更少。

使用 [嘗試電子郵件] 傳送電子郵件

[嘗試電子郵件] 可協助您開始使用 Azure 通訊服務向所需的收件者傳送電子郵件，並驗證應用程式設定以傳送電子郵件。 其也有助於使用以所選慣用語言撰寫的程式碼片段，快速地開始開發電子郵件通知。

要向收件者傳送訊息，並指定訊息主題和正文：

  1. 從所佈建的 Azure 通訊服務資源的概觀頁面，在左側瀏覽面板上按一下 [電子郵件] 下方的 [嘗試電子郵件]。

    顯示試用電子郵件左側瀏覽面板的螢幕擷取畫面。

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

    顯示已驗證網域下拉式清單的螢幕擷取畫面。

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

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

    顯示如何篩選並選取其中一個要連線之已驗證電子郵件網域的螢幕擷取畫面。

  4. 按一下 傳送。

    顯示其中一個已驗證的電子郵件網域現在已連線的螢幕擷取畫面。

  5. 電子郵件傳送成功。

    此螢幕擷取畫面顯示成功傳送電子郵件。

  6. 您還可以複製範例程式碼片段以傳送用來在範例專案中發送通知的電子郵件。

    • 選取您選擇的語言

    • 按一下 [插入我的連線]

    • 按一下 [複製]

      顯示要傳送電子郵件的代碼段螢幕擷取畫面。

  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_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 監視器或 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 通訊服務的電子郵件傳送體驗。

了解電子郵件物件模型

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

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

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

狀態 描述
NotStarted 我們目前不會從我們的服務傳送此狀態。
執行中 電子郵件傳送作業目前正在進行中並且正在進行處理。
成功 電子郵件傳送作業完成且沒有錯誤，並且電子郵件已可進行傳遞。 您可以透過 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

安裝套件

若您仍在應用程式目錄中，請使用 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 方法。 將此程式碼加入到 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";

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

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

使用 Azure 通訊服務 JavaScript 電子郵件用戶端程式庫傳送電子郵件訊息，開始使用 Azure 通訊服務。

秘訣

使用 GitHub 上的基本電子郵件傳送和進階電子郵件傳送範例程式碼，透過 Azure 通訊服務快速開始傳送電子郵件體驗。

了解電子郵件物件模型

以下類別和介面處理適用於 JavaScript 的 Azure 通訊服務電子郵件用戶端程式庫的某些功能。

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

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

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

先決條件

完成此文章可能會在您的 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 的檔案。 將 main 中的 package.json 屬性變更為 send-email.js。 以下部分演示如何將本文的原始程式碼添加到新建立的檔案中。

安裝套件

使用 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);

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

基本的電子郵件傳送

傳送電子郵件訊息

若要傳送電子郵件訊息，請從 beginSend 呼叫 EmailClient 函式。 此方法傳回一個輪詢者，其檢查作業的狀態並在完成後擷取結果。


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 Azure 範例：傳送適用於 JavaScript 的電子郵件下載範例應用程式。

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

秘訣

使用 GitHub 上的基本電子郵件傳送和進階電子郵件傳送範例程式碼，透過 Azure 通訊服務快速開始傳送電子郵件體驗。

了解電子郵件物件模型

以下類別和介面處理適用於 Java 的 Azure 通訊服務電子郵件 SDK 的一些主要功能。

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

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

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

先決條件

完成此文章可能會在您的 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 檔案是專案的「專案物件模型」(POM)。

安裝套件

在文字編輯器中開啟 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.*;

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 地址。

若要傳送電子郵件訊息，請從 beginSend 呼叫 EmailClient 函式。

在非同步用戶端上呼叫 beginSend 會傳回您可以訂閱 PollerFlux 物件。 電子郵件傳送作業完成後，將觸發訂閱方法中定義的回呼。 請注意，在設定訂閱者之前，不會傳送電子郵件的初始要求。

Duration MAIN_THREAD_WAIT_TIME = Duration.ofSeconds(30);

// ExecutorService to run the polling in a separate thread
ExecutorService executorService = Executors.newSingleThreadExecutor();

PollerFlux<EmailSendResult, EmailSendResult> poller = emailAsyncClient.beginSend(emailMessage);

executorService.submit(() -> {
    // The initial request is sent out as soon as we subscribe the to PollerFlux object
    poller.subscribe(
        response -> {
            if (response.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
                System.out.printf("Successfully sent the email (operation id: %s)\n", response.getValue().getId());
            }
            else {
                // The operation ID can be retrieved as soon as the first response is received from the PollerFlux.
                System.out.println("Email send status: " + response.getStatus() + ", operation id: " + response.getValue().getId());
            }
        },
        error -> {
            System.out.println("Error occurred while sending email: " + error.getMessage());
        }
    );
});

// In a real application, you might have a mechanism to keep the main thread alive.
// For this sample we will keep the main thread alive for 30 seconds to make sure the child thread has time to receive the SUCCESSFULLY_COMPLETED status.
try {
    Thread.sleep(MAIN_THREAD_WAIT_TIME.toMillis());
} catch (InterruptedException e) {
    e.printStackTrace();
}

executorService.shutdown();
System.out.println("Main thread ends.");

執行程式碼

  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 Azure 範例：傳送適用於 Java 的電子郵件下載範例應用程式

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

秘訣

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

了解電子郵件物件模型

下列 JSON 訊息範本與回應物件會示範適用於 Python 的 Azure 通訊服務電子郵件 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 監視器或 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 檔案中。

安裝套件

仍在應用程式目錄時，請使用下列命令安裝適用於 Python 的 Azure 通訊服務電子郵件 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 範例：傳送適用於 Python 的電子郵件下載範例應用程式

先決條件

  • 包含作用中訂用帳戶的 Azure 帳戶，或建立免費 Azure 帳戶。

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

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

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

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

傳送電子郵件

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

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

    使用量

    1. 在要新增動作的步驟底下，選取 [新增步驟]。 或者，若要在步驟之間新增動作，請將指標移到這些步驟之間的箭號上、選取加號 (+)，然後選取 [新增動作]。

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

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

      顯示 Azure 通訊服務電子郵件連接器 [傳送電子郵件] 動作的螢幕擷取畫面。

    Standard

    1. 在要新增動作的步驟底下，選取加號 (+)。 或者，若要在步驟之間新增動作，請將指標移到這些步驟之間的箭號上、選取加號 (+)，然後選取 [新增動作]。

    2. 在 [新增動作] 搜尋方塊底下，選取 [執行階段] 下拉式清單中的 [Premium]。 在搜尋方塊中，輸入 Azure 通訊電子郵件。

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

  2. 提供連線的名稱。

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

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

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

      顯示 Azure 通訊服務連接字串的螢幕擷取畫面。

  4. 當您完成時，選取 [建立]。

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

    顯示 Azure 通訊服務電子郵件連接器傳送電子郵件動作輸入的螢幕擷取畫面。

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

測試您的工作流程

根據您擁有的是使用量工作流程還是標準工作流程，手動啟動您的工作流程：

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

工作流程會建立使用者、為該使用者核發存取權杖，然後移除並刪除該使用者。 工作流程成功執行後，您可以檢查這些動作的輸出。

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

清除工作流程資源

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

開始 Azure 通訊服務，使用 Azure PowerShell 通訊模組傳送電子郵件。

完成此文章可能會在您的 Azure 帳戶中產生一小筆成本，約為幾美分或更少。

先決條件

先決條件檢查

  • 在 Windows PowerShell 中，執行 Get-Module -ListAvailable -Name Az.Communication 命令檢查是否已安裝通訊模組。
  • 若要檢視以您的電子郵件通訊服務資源驗證的網域，請登入 Azure 入口網站。 找到您的電子郵件通訊服務資源，然後從左側瀏覽面板中打開 [佈建網域] 索引標籤。

設定

安裝通訊模組

使用 Install-Module -Name Az.Communication 命令安裝適用於 Azure PowerShell 的 Azure 通訊服務模組。

Install-Module -Name Az.Communication

安裝通訊模組之後，請執行 Get-Command -Module Az.Communication 命令以取得所有通訊模組。

Get-Command -Module Az.Communication

傳送電子郵件訊息

將要傳送給一個或多個收件者的電子郵件加入佇列，其中僅包含必填欄位。

$emailRecipientTo = @(
   @{
        Address = "<emailalias@emaildomain.com>"
        DisplayName = "Email DisplayName"
    }
)

$message = @{
    ContentSubject = "Test Email"
    RecipientTo = @($emailRecipientTo)  # Array of email address objects
    SenderAddress = '<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>'   
    ContentPlainText = "This is the first email from ACS - Azure PowerShell"    
}

Send-AzEmailServicedataEmail -Message $Message -endpoint "<yourEndpoint>"

取代程式碼中的下列內容：

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

將要傳送給一個或多個收件者的電子郵件與所有欄位一起加入佇列。

$emailRecipientTo = @(
   @{
        Address = "<emailalias@emaildomain.com>"
        DisplayName = "Email DisplayName"
    },
   @{
        Address = "<emailalias1@emaildomain.com>"
        DisplayName = "Email DisplayName"
    }
)

$fileBytes1 = [System.IO.File]::ReadAllBytes("<file path>")

$fileBytes2 = [System.IO.File]::ReadAllBytes("<image file path>")

$emailAttachment = @(
    @{
        ContentInBase64 = $fileBytes1
        ContentType = "<text/plain>"
        Name = "<test.txt>"
    },
    @{
        ContentInBase64 = $fileBytes2
        ContentType = "<image/png>"
        Name = "<inline-attachment.png>"
        contentId = "<inline-attachment>"
    }
)

$headers = @{
    "Key1" = "Value1"
    "Key2" = "Value2"
    "Importance" = "high"
}

$emailRecipientBcc = @(
   @{
        Address = "<emailbccalias@emaildomain.com>"
        DisplayName = "Email DisplayName"
    }
)

$emailRecipientCc = @(
   @{
        Address = "<emailccalias@emaildomain.com>"
        DisplayName = "Email DisplayName"
    }
)

$emailRecipientReplyTo = @(
   @{
        Address = "<emailreplytoalias@emaildomain.com>"
        DisplayName = "Email DisplayName"
    }
)

$message = @{
    ContentSubject = "Test Email"
    RecipientTo = @($emailRecipientTo)  # Array of email address objects
    SenderAddress = '<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>'
    Attachment = @($emailAttachment) # Array of attachments
    ContentHtml = "<html><head><title>Enter title</title></head><body><img src='cid:inline-attachment' alt='Company Logo'/><h1>This is the first email from ACS - Azure PowerShell</h1></body></html>"
    ContentPlainText = "This is the first email from ACS - Azure PowerShell"
    Header = $headers  # Importance = high/medium/low or X-Priority = 2/3/4  
    RecipientBcc = @($emailRecipientBcc) # Array of email address objects
    RecipientCc = @($emailRecipientCc) # Array of email address objects
    ReplyTo = @($emailRecipientReplyTo) # Array of email address objects
    UserEngagementTrackingDisabled = $true
}

Send-AzEmailServicedataEmail -Message $Message -endpoint "<yourEndpoint>"

取代程式碼中的下列內容：

  • 將 <yourEndpoint> 取代為您的端點。
  • 將 <emailalias@emaildomain.com> and <emailalias1@emaildomain.com> 取代為要作為訊息傳送目的地的電子郵件地址。
  • 將 <file path> and <image file path> 取代為您要傳送之附件的實際檔案路徑。
  • 將 <text/plain> and <image/png> 取代為您附件的適當內容類型。
  • 將 <test.txt> and <inline-attachment.png> 取代為附件的檔案名稱。
  • 以內嵌附件的 Content-ID 取代 <inline-attachment>。
  • 將 <emailbccalias@emaildomain.com> 取代為您想要以密件副本將訊息傳送至的電子郵件地址。
  • 將 <emailccalias@emaildomain.com> 取代為您想要以副本將訊息傳送至的電子郵件地址。
  • 將 <emailreplytoalias@emaildomain.com> 取代為您要傳送回覆的電子郵件位址。
  • 將 <donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net> 取代為已驗證網域的 MailFrom 地址。

選擇性參數

Azure PowerShell 提供下列選用參數。

  • ContentHtml 可用來指定電子郵件的 HTML 內文。

  • ContentPlainText 用來指定電子郵件的純文字內文。

  • Attachment 會設定電子郵件附件清單。 此參數接受檔案路徑或附件物件的陣列。 我們將電子郵件要求 (包括一般附件和內嵌附件) 的總大小限制為 10 MB。

  • Header 要傳遞的自訂電子郵件標頭，並設定電子郵件重要性等級 (高、標準或低)。

  • BCC 欄位的收件者 RecipientBcc 陣列。

  • CC 欄位的收件者 RecipientCc 陣列。

  • ReplyTo 接收者回覆傳送的郵件地址陣列。

  • UserEngagementTrackingDisabled 指示如果已在控制平面中啟用資源級使用者參與度追蹤設定，是否需要為此要求停用使用者參與度追蹤。

您還可以使用具有 RecipientCc 和 RecipientBcc 類似於 RecipientTo的收件人清單。 RecipientTo、RecipientCc 或 RecipientBcc 中至少必須有一個收件者。

疑難排解

電子郵件傳遞

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

重要事項

輪詢傳送作業狀態所傳回的成功結果僅可驗證電子郵件成功發送已可傳遞的事實。 如需收件者端傳遞狀態的詳細資訊，請參閱 如何處理電子郵件事件。

電子郵件節流

如果您的應用程式卡住，可能是因為電子郵件傳送速度被限制。 您可以透過記錄或實施自訂原則來處理分層限制。

附註

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

清除 Azure 通訊服務資源

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

後續步驟

本文說明如何使用 Azure 通訊服務傳送電子郵件。 您也可以：

  • Last updated on