快速入門:如何使用 Azure 通訊服務傳送電子郵件
注意
請透過進行這份簡短的調查,與我們分享您對 Azure 通訊服務 的看法和意見反應。
在本快速入門中,您將瞭解如何使用我們的電子郵件 SDK 來傳送電子郵件。
使用通訊服務嘗試傳送電子郵件訊息,開始使用 Azure 通訊服務。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- 適用於您作業系統的最新版本 .NET Core 用戶端連結庫 。
- 已建立並準備好布建網域 的 Azure 電子郵件通訊服務資源 開始使用建立電子郵件通訊資源
- 使用電子郵件網域連線的作用中通訊服務資源。 開始使用使用通訊資源 連線 電子郵件資源
完成此快速入門,您的 Azure 帳戶中會產生幾美分或更少成本。
使用 Try Email 傳送電子郵件
嘗試電子郵件可協助您使用 Azure 通訊服務 開始傳送電子郵件給所需的收件者,以及驗證應用程式傳送電子郵件的設定。 它也有助於使用您慣用的語言選擇的代碼段,快速啟動電子郵件通知開發。
若要將郵件傳送給收件者,以及指定郵件主旨和本文,
使用 Azure CLI 通訊延伸模組來傳送電子郵件訊息,開始使用 Azure 通訊服務。
完成此快速入門,您的 Azure 帳戶中會產生幾美分或更少成本。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- 已建立並準備好布建網域的 Azure 電子郵件通訊服務資源。 開始建立電子郵件通訊資源。
- 線上到電子郵件網域及其 連接字串的作用中 Azure 通訊服務 資源。 開始使用使用 Azure 通訊資源連接電子郵件通訊資源。
- 最新的 Azure CLI。
先決條件檢查
- 在終端機或命令視窗中,執行
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 帳戶。 免費建立帳戶。
- 適用於您作業系統的最新版本 .NET Core 用戶端連結庫 。
- 已建立並準備好布建網域 的 Azure 電子郵件通訊服務資源 開始使用建立電子郵件通訊資源
- 使用電子郵件網域和 連線 ion String 連線的作用中通訊服務資源。 開始使用使用通訊資源 連線 電子郵件資源
完成此快速入門,您的 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
範例指令碼
使用通訊服務 JS 電子郵件用戶端連結庫來傳送電子郵件訊息,開始使用 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 | 如果電子郵件傳送作業未成功且發生錯誤,則存在的屬性。 未傳送電子郵件。 結果包含錯誤物件,其中包含失敗原因的詳細數據。 |
必要條件
- Node.js (~14) 。
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- 已建立並準備好布建網域的 Azure 電子郵件通訊服務資源。 開始建立電子郵件通訊資源。
- 線上到電子郵件網域及其 連接字串的作用中 Azure 通訊服務 資源。 開始使用使用 Azure 通訊資源連接電子郵件通訊資源。
完成此快速入門,您的 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
範例指令碼
使用通訊服務 Java 電子郵件 SDK 來傳送電子郵件訊息,開始使用 Azure 通訊服務。
瞭解電子郵件物件模型
下列類別和介面會處理 Azure 通訊服務 Email SDK for Python 的一些主要功能。
名稱 | 描述 |
---|---|
EmailAddress | 這個類別包含電子郵件地址和顯示名稱的選項。 |
EmailAttachment | 此介面會藉由接受唯一標識碼、電子郵件附件MIME類型字串和內容位元組字串,來建立電子郵件附件。 |
EmailClient | 所有電子郵件功能都需要這個類別。 您可以使用 連接字串 將其具現化,並用它來傳送電子郵件訊息。 |
EmailMessage | 這個類別結合了發件者、內容和收件者。 您也可以選擇性地新增自訂標頭、附件和回覆電子郵件位址。 |
EmailSendResult | 這個類別會保存電子郵件傳送作業的結果。 它有作業標識碼、作業狀態和錯誤物件(適用時)。 |
EmailSendStatus | 這個類別代表電子郵件傳送作業的狀態集。 |
EmailSendResult 會在執行的電子郵件作業上傳回下列狀態。
狀態名稱 | 描述 |
---|---|
NOT_STARTED | 我們目前不會從我們的服務傳送此狀態。 |
IN_PROGRESS | 電子郵件傳送作業目前正在進行中並正在處理。 |
SUCCESSFULLY_COMPLETED | 電子郵件傳送作業已完成,且電子郵件無法傳遞。 您可以透過 Azure 監視器或透過 Azure 事件方格 取得有關此階段以外電子郵件傳遞的任何詳細狀態。 瞭解如何訂閱電子郵件事件 |
失敗 | 電子郵件傳送作業未成功,併發生錯誤。 未傳送電子郵件。 結果包含錯誤物件,其中包含失敗原因的詳細數據。 |
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立帳戶。
- Java Development Kit (JDK) 第 8 版或更新版本。
- Apache Maven。
- 已部署的通訊服務資源和 連接字串。 如需詳細資訊,請參閱 建立通訊服務資源。
- 建立 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 位址。
執行程式碼
流覽至包含pom.xml檔案的目錄,並使用
mvn
命令編譯專案。mvn compile
建置套件。
mvn package
執行下列
mvn
命令以執行應用程式。mvn exec:java -D"exec.mainClass"="com.communication.quickstart.App" -D"exec.cleanupDaemonThreads"="false"
範例指令碼
使用通訊服務 Python 電子郵件 SDK 傳送電子郵件訊息,開始使用 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 3.7+。
- 已建立並準備好布建網域的 Azure 電子郵件通訊服務資源。 開始建立電子郵件通訊資源。
- 線上到電子郵件網域及其 連接字串的作用中 Azure 通訊服務 資源。 開始使用使用 Azure 通訊資源連接電子郵件通訊資源。
完成此快速入門,您的 Azure 帳戶中會產生幾美分或更少成本。
注意
我們也可以從自己的已驗證網域傳送電子郵件。 將自定義已驗證的網域新增至電子郵件通訊服務。
先決條件檢查
- 在終端機或命令視窗中,執行
python --version
命令來檢查是否已安裝 Python。 - 若要檢視使用電子郵件通訊服務資源驗證的網域,請登入 Azure 入口網站。 找出您的電子郵件通訊服務資源,然後從左側瀏覽窗格開啟 [ 布建網域] 索引 卷標。
設定應用程式環境
若要設定傳送電子郵件的環境,請執行下列各節中的步驟。
建立新的 Python 應用程式
開啟終端機或命令視窗。 然後使用下列命令來建立虛擬環境並加以啟用。 此命令會為您的應用程式建立新的目錄。
python -m venv email-quickstart
瀏覽至虛擬環境的根目錄,並使用下列命令加以啟用。
cd email-quickstart .\Scripts\activate
使用文本編輯器在專案根目錄中建立名為 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
範例指令碼
必要條件
具有作用中訂用帳戶的 Azure 帳戶,或 免費建立 Azure 帳戶。
作用中 Azure 通訊服務 資源,或建立通訊服務資源。
作用中的 Azure Logic Apps 資源(邏輯應用程式)和工作流程,或使用您想要使用的觸發程式建立新的邏輯應用程式資源和工作流程。 目前,Azure 通訊服務 電子郵件連接器只提供動作,因此您的邏輯應用程式工作流程至少需要觸發程式。 您可以建立 取用 或 標準 邏輯應用程式資源。
與 Azure 電子郵件網域連線 Azure 通訊服務 資源。
傳送電子郵件
若要使用 Azure 通訊服務 電子郵件連接器將新步驟新增至您的工作流程,請遵循下列步驟:
在設計工具中,開啟邏輯應用程式工作流程。
耗用
在您要新增動作的步驟下,選取 [ 新增步驟]。 或者,若要在步驟之間新增動作,請將指標移至這些步驟之間的箭號上方,選取加號 (+),然後選取 [ 新增動作]。
在 [ 選擇作業 搜尋] 方塊底下,選取 [ 標準]。 在搜尋方塊中,輸入 通訊服務電子郵件。
從動作清單中,選取 [ 傳送電子郵件]。
標準
在您要新增動作的步驟下,選取加號 (+)。 或者,若要在步驟之間新增動作,請將指標移至這些步驟之間的箭號上方,選取加號 (+),然後選取 [ 新增動作]。
在 [ 選擇作業 搜尋] 方塊底下,選取 [Azure]。 在搜尋方塊中,輸入 通訊服務電子郵件。
從動作清單中,選取 [ 傳送電子郵件]。
提供連線的名稱。
輸入 Azure 通訊服務資源的 連接字串。 若要尋找此字串,請遵循下列步驟:
在 Azure 入口網站 中,開啟您的 Azure 通訊服務資源。
在資源功能表上,選取 [設定] 底下的 [金鑰],然後複製 連接字串。
完成時,選取建立。
在 [來源] 欄位中,使用您在必要條件中設定的電子郵件位址。 輸入 [到]、[主旨] 和 [本文] 欄位的值,例如:
儲存您的工作流程您 在設計師工具列上選取儲存。
測試工作流程
根據您是否有取用或標準工作流程,手動啟動您的工作流程:
- 取用:在設計工具工具列上,選取 [執行觸發程序>執行]。
- 標準:在工作流程功能表上,選取 [ 概觀]。 在工具列上,選取 [執行觸發程序>執行]。
工作流程會建立使用者、發出該使用者的存取令牌,然後移除和刪除使用者。 您可以在工作流程順利執行之後檢查這些動作的輸出。
您應該指定的位址收到電子郵件。 此外,您可以使用 [ 取得電子郵件訊息狀態 ] 動作來檢查透過 [傳送電子郵件 ] 動作傳送的電子郵件狀態。 如需更多動作,請檢閱 Azure 通訊服務 電子郵件連接器參考檔。
清除工作流程資源
若要清除邏輯應用程式資源、工作流程和相關資源,請檢閱 如何清除取用邏輯應用程式資源 ,或 如何清除標準邏輯應用程序資源。
疑難排解
電子郵件傳遞
若要針對與電子郵件傳遞相關的問題進行疑難解答,您可以 取得電子郵件傳遞 狀態以擷取傳遞詳細數據。
重要
輪詢傳送作業狀態所傳回的成功結果只會驗證已成功傳送電子郵件以傳遞的事實。 若要取得收件者端傳遞狀態的其他資訊,您必須參考 如何處理電子郵件事件。
電子郵件節流
如果您看到應用程式已停止回應,可能是因為電子郵件傳送受到節流處理。 您可以 透過記錄或實作自定義原則來處理此作業。
注意
此沙箱設定可協助開發人員開始建置應用程式。 一旦應用程式準備好上線,您可以逐漸要求增加傳送量。 如果您需要傳送超過速率限制的訊息量,請提交支援要求以提高您所需的傳送限制。
清除 Azure 通訊服務資源
若要清除和移除通訊服務訂用帳戶,您可以刪除資源或資源群組。 刪除資源群組也會刪除任何其他相關聯的資源。 深入瞭解清除 資源。
下一步
在本快速入門中,您已瞭解如何使用 Azure 通訊服務 傳送電子郵件。 您可能也想要:
- 了解 電子郵件概念。
- 熟悉電子郵件客戶端連結庫。
- 深入瞭解如何使用 Azure 通訊服務 從Power Automate 傳送聊天訊息。
- 深入瞭解存取令牌簽入建立和管理 Azure 通訊服務 使用者和存取令牌。