快速入門：傳送內嵌附件的電子郵件

發行項
10/03/2024

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

藉由使用通訊服務 .NET 電子郵件用戶端程式庫來傳送電子郵件訊息，以開始使用 Azure 通訊服務。

提示

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

了解電子郵件物件模型

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

名稱	描述
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 電子郵件通訊服務資源，並已準備佈建從建立電子郵件通訊資源開始著手的網域
使用電子郵件網域和連接字串進行連線的作用中通訊服務資源。將通訊資源與電子郵件資源連線來開始著手

完成本快速入門後，您的 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);

若要使用 Azure Active Directory 進行驗證，請藉由使用 dotnet add package 命令安裝適用於 .NET 的 Azure.Identity 程式庫套件。

dotnet add package Azure.Identity

在文字編輯器中開啟 Program.cs，並將 Main 方法的本文取代為程式碼，以使用 DefaultAzureCredential 來初始化 EmailClient。 Azure 身分識別 SDK 會在執行階段讀取三個環境變數中的值，以驗證應用程式。了解如何建立 Azure Active Directory 已註冊應用程式並且設定環境變數。

// This code demonstrates how to authenticate to your Communication Service resource using
// DefaultAzureCredential and the environment variables AZURE_CLIENT_ID, AZURE_TENANT_ID,
// and AZURE_CLIENT_SECRET.
string resourceEndpoint = "<ACS_RESOURCE_ENDPOINT>";
EmailClient emailClient = new EmailClient(new Uri(resourceEndpoint), new DefaultAzureCredential());

您也可以使用 AzureKeyCredential 來驗證電子郵件用戶端。 key 和 endpoint 都可以在通訊服務資源中 [設定] 底下的 [金鑰] 窗格中找到。

var key = new AzureKeyCredential("<your-key-credential>");
var endpoint = new Uri("<your-endpoint-uri>");

var emailClient = new EmailClient(endpoint, key);

傳送內嵌附件的電子郵件訊息

我們可以定義一或多個 EmailAttachment 物件、為每個物件定義唯 ContentId 一的附件，並將其新增至 EmailMessage 物件，以新增內嵌附件。讀取附件檔案，並使用 Base64 進行編碼。

var jpgFilePath = "./inline-attachment.jpg";
byte[] jpgBytes = File.ReadAllBytes(jpgFilePath);
var jpgBinaryData = new BinaryData(jpgBytes);
var jpgInlineAttachment = new EmailAttachment(
    "inline-attachment.jpg",
    "image/jpeg",
    jpgBinaryData);
jpgInlineAttachment.ContentId = "my-inline-attachment-1";

var pngFilePath = "./inline-attachment.png";
byte[] pngBytes = File.ReadAllBytes(pngFilePath);
var pngBinaryData = new BinaryData(pngBytes);
var pngInlineAttachment = new EmailAttachment(
    "inline-attachment.png",
    "image/png",
    pngBinaryData);
pngInlineAttachment.ContentId = "my-inline-attachment-2";

在訊息的 HTML 內文中，我們可以藉由在標籤的來源<img>內參考影像ContentId來內嵌影像。

var emailContent = new EmailContent("Welcome to Azure Communication Services Email")
{
    PlainText ="This email message is sent from Azure Communication Services Email using the .NET SDK.",
    Html = "<html><h1>HTML body inline images:</h1><img src=\"cid:my-inline-attachment-1\" /><img src=\"cid:my-inline-attachment-2\" /></html>"
};

var emailMessage = new EmailMessage(
    senderAddress: "donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net"
    recipientAddress: "emailalias@contoso.com"
    content: emailContent);

emailMessage.Attachments.Add(jpgInlineAttachment);
emailMessage.Attachments.Add(pngInlineAttachment);

try
{
    EmailSendOperation emailSendOperation = emailClient.Send(WaitUntil.Completed, emailMessage);
    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}");
}

注意

一般附件也可以與內嵌附件結合。定義 ContentId 會將附件視為內嵌，而沒有 ContentId 的附件則會被視為一般附件。

允許的 MIME 類型

雖然大多數新式用戶端都支援內嵌附件，但內嵌附件的轉譯行為主要取決於收件者的電子郵件用戶端。基於這個理由，建議盡可能使用更常見的影像格式，例如.png、.jpg或.gif。如需電子郵件附件可接受 MIME 類型的詳細資訊，請參閱允許的 MIME 類型文件。

範例指令碼

您可以從 GitHub 下載示範此動作的範例應用程式

藉由使用通訊服務 JS 電子郵件用戶端程式庫來傳送電子郵件訊息，以開始使用 Azure 通訊服務。

提示

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

了解電子郵件物件模型

下列類別和介面會處理 Azure 通訊服務的聊天用戶端程式庫的一些主要 JavaScript 功能。

名稱	描述
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);

您也可以使用 Azure 身分識別程式庫向 Microsoft Entra ID 進行驗證。若要在下列程式碼片段中使用 DefaultAzureCredential 提供者，或與 Azure SDK 一起提供的其他認證提供者，請安裝 @azure/identity 套件：

npm install @azure/identity

@azure/identity 套件提供應用程式可用來驗證的各種認證類型。 @azure/identity 的讀我檔案提供更多詳細資料和範例，讓您開始使用。需要 AZURE_CLIENT_SECRET、AZURE_CLIENT_ID 和 AZURE_TENANT_ID 環境變數，才能建立 DefaultAzureCredential 物件。

import { DefaultAzureCredential } from "@azure/identity";
import { EmailClient } from "@azure/communication-email";

const endpoint = "https://<resource-name>.communication.azure.com";
let credential = new DefaultAzureCredential();

const emailClient = new EmailClient(endpoint, credential);

您也可以使用 AzureKeyCredential 來驗證電子郵件用戶端。 key 和 endpoint 都可以在通訊服務資源中 [設定] 底下的 [金鑰] 窗格中找到。

const { EmailClient, KnownEmailSendStatus } = require("@azure/communication-email");
const { AzureKeyCredential } = require("@azure/core-auth");
require("dotenv").config();

var key = new AzureKeyCredential("<your-key-credential>");
var endpoint = "<your-endpoint-uri>";

const emailClient = new EmailClient(endpoint, key);

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

傳送內嵌附件的電子郵件訊息

我們可以藉由定義一或多個附件物件來新增內嵌附件，請務必為每個物件包含唯 contentId 一的附件，並將其新增至訊息。讀取附件檔案，並使用 Base64 進行編碼。

const jpgFilePath = "./inline-attachment.jpg";
const pngFilePath = "./inline-attachment.png";

const inlineAttachments = [
    {
        name: path.basename(jpgFilePath),
        contentId: "my-inline-attachment-1"
        contentType: "image/jpeg",
        contentInBase64: readFileSync(jpgFilePath, "base64"),
    },
    {
        name: path.basename(pngFilePath),
        contentId: "my-inline-attachment-2"
        contentType: "image/png",
        contentInBase64: readFileSync(pngFilePath, "base64"),
    }
];

在訊息的 HTML 內文中，我們可以藉由在標籤的來源<img>內參考影像contentId來內嵌影像。

const message = {
  sender: "<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.",
    html: "<html><h1>HTML body inline images:</h1><img src=\"cid:my-inline-attachment-1\" /><img src=\"cid:my-inline-attachment-2\" /></html>"
  },
  recipients: {
    to: [
      {
        address: "<emailalias@contoso.com>",
        displayName: "Customer Name",
      }
    ]
  },
  attachments: inlineAttachments
};

const poller = await emailClient.beginSend(message);
const response = await poller.pollUntilDone();

注意

一般附件也可以與內嵌附件結合。定義 contentId 會將附件視為內嵌，而沒有 contentId 的附件則會被視為一般附件。

允許的 MIME 類型

範例指令碼

您可以從 GitHub 下載示範此動作的範例應用程式

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

提示

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

了解電子郵件物件模型

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

名稱	描述
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 電子郵件通訊服務資源以開始傳送電子郵件。
適用於開發環境的設定受控識別，請參閱使用受控識別授權存取。

完成本快速入門後，您的 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)。

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

DefaultAzureCredential 物件必須透過 credential() 方法傳遞至 EmailClientBuilder。端點也必須透過 endpoint() 方法來設定。

需要 AZURE_CLIENT_SECRET、AZURE_CLIENT_ID 和 AZURE_TENANT_ID 環境變數，才能建立 DefaultAzureCredential 物件。

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<resource-name>.communication.azure.com/";
EmailClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

您也可以使用從 Azure 入口網站中的 Azure 通訊資源取得的端點和 Azure 金鑰認證，建立和驗證電子郵件用戶端。

String endpoint = "https://<resource-name>.communication.azure.com";
AzureKeyCredential azureKeyCredential = new AzureKeyCredential("<access-key>");
EmailClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(azureKeyCredential)
    .buildClient();

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

傳送內嵌附件的電子郵件訊息

byte[] jpgContent = Files.readAllBytes(new File("./inline-attachment.jpg").toPath());
byte[] jpgEncodedContent = Base64.getEncoder().encodeToString(jpgContent).getBytes();
EmailAttachment jpgInlineAttachment = new EmailAttachment(
    "inline-attachment.jpg",
    "image/jpeg",
    BinaryData.fromBytes(jpgEncodedContent)
).setContentId("my-inline-attachment-1");

byte[] pngContent = Files.readAllBytes(new File("./inline-attachment.png").toPath());
byte[] pngEncodedContent = Base64.getEncoder().encodeToString(pngContent).getBytes();
EmailAttachment pngInlineAttachment = new EmailAttachment(
    "inline-attachment.png",
    "image/png",
    BinaryData.fromBytes(pngEncodedContent)
).setContentId("my-inline-attachment-2");

在訊息的 HTML 內文中，我們可以藉由在標籤的來源<img>內參考影像ContentId來內嵌影像。

EmailMessage message = new EmailMessage()
    .setSenderAddress(senderAddress)
    .setToRecipients(recipientAddress)
    .setSubject("Welcome to Azure Communication Services Email")
    .setBodyPlainText("This email message is sent from Azure Communication Services Email using the Java SDK.");
    .setBodyHtml("<html><h1>HTML body inline images:</h1><img src=\"cid:my-inline-attachment-1\" /><img src=\"cid:my-inline-attachment-2\" /></html>")
    .setAttachments(jpgInlineAttachmentContent, pngInlineAttachmentContent);

SyncPoller<EmailSendResult, EmailSendResult> poller = emailClient.beginSend(message, null);
PollResponse<EmailSendResult> response = poller.waitForCompletion();

System.out.println("Operation Id: " + response.getValue().getId());

注意

一般附件也可以與內嵌附件結合。定義 ContentId 會將附件視為內嵌，而沒有 ContentId 的附件則會被視為一般附件。

允許的 MIME 類型

範例指令碼

您可以從 GitHub 下載示範此動作的範例應用程式

藉由使用通訊服務 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": [
        {
            "name": "str"  # Name of the attachment. Required.
            "contentType": "str",  # MIME type of the content being attached. Required.
            "contentInBase64": "str",  # Base64 encoded contents of the attachment. Required.
            "contentId": "str" # Unique identifier (CID) to reference an inline attachment. Optional
        }
    ],
    "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

仍在應用程式目錄時，請使用下列命令安裝適用於 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>)

您也可以使用 Active Directory 驗證，該驗證使用 DefaultAzureCredential。

from azure.communication.email import EmailClient
from azure.identity import DefaultAzureCredential

# To use Azure Active Directory Authentication (DefaultAzureCredential) make sure to have AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_CLIENT_SECRET as env variables.
endpoint = "https://<resource-name>.communication.azure.com"
email_client = EmailClient(endpoint, DefaultAzureCredential())

您也可以使用 AzureKeyCredential 來驗證電子郵件用戶端。 key 和 endpoint 都可以在通訊服務資源中 [設定] 底下的 [金鑰] 窗格中找到。

from azure.communication.email import EmailClient
from azure.core.credentials import AzureKeyCredential

key = AzureKeyCredential("<your-key-credential>");
endpoint = "<your-endpoint-uri>";

email_client = EmailClient(endpoint, key);

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

傳送內嵌附件的電子郵件訊息

我們可以藉由定義一或多個 attachments來新增內嵌附件，請務必為每個附加一個唯 contentId 一的附件，並將其新增至訊息。讀取附件檔案，並使用 Base64 進行編碼。將位元組解碼為字串，並將其傳遞至 attachment 物件。

import base64

with open("./inline-attachment.jpg", "rb") as file:
    jpg_file_bytes_b64 = base64.b64encode(file.read())

with open("./inline-attachment.png", "rb") as file:
    png_file_bytes_b64 = base64.b64encode(file.read())

inlineAttachments = [
    {
        "name": "inline-attachment.jpg",
        "contentId": "my-inline-attachment-1",
        "contentType": "image/jpeg",
        "contentInBase64": jpg_file_bytes_b64.decode()
    },
    {
        "name": "inline-attachment.png",
        "contentId": "my-inline-attachment-2",
        "contentType": "image/png",
        "contentInBase64": png_file_bytes_b64.decode()
    }
]

在訊息的 HTML 內文中，我們可以藉由在標籤的來源<img>內參考影像contentId來內嵌影像。

message = {
    "content": {
        "subject": "Welcome to Azure Communication Services Email",
        "plainText": "This email message is sent from Azure Communication Services Email using the Python SDK.",
        "html": "<html><h1>HTML body inline images:</h1><img src=\"cid:my-inline-attachment-1\" /><img src=\"cid:my-inline-attachment-2\" /></html>"
    },
    "recipients": {
        "to": [
            {
                "address": "<emailalias@contoso.com>",
                "displayName": "Customer Name"
            }
        ]
    },
    "senderAddress": "<donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net>",
    "attachments": inlineAttachments
}

poller = email_client.begin_send(message)
result = poller.result()

注意

一般附件也可以與內嵌附件結合。定義 contentId 會將附件視為內嵌，而沒有 contentId 的附件則會被視為一般附件。

允許的 MIME 類型

範例指令碼

您可以從 GitHub 下載示範此動作的範例應用程式

疑難排解

電子郵件傳遞

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

重要

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

電子郵件節流

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

注意

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

清除 Azure 通訊服務資源

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

下一步

在本快速入門中，您已了解如何使用 Azure 通訊服務在傳送電子郵件時手動輪詢狀態。

您可能也會想要：

共用方式為

快速入門：傳送內嵌附件的電子郵件

了解電子郵件物件模型

必要條件

先決條件檢查

建立新的 C# 應用程式

Install the package

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

傳送內嵌附件的電子郵件訊息

允許的 MIME 類型

範例指令碼

了解電子郵件物件模型

必要條件

先決條件檢查

設定應用程式環境

建立新的 Node.js 應用程式

Install the package

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

傳送內嵌附件的電子郵件訊息

允許的 MIME 類型

範例指令碼

了解電子郵件物件模型

必要條件

先決條件檢查

設定應用程式環境

建立新的 Java 應用程式

Install the package

設定應用程式架構

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

傳送內嵌附件的電子郵件訊息

允許的 MIME 類型

範例指令碼

了解電子郵件物件模型

必要條件

先決條件檢查

設定應用程式環境

建立新的 Python 應用程式

Install the package

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

傳送內嵌附件的電子郵件訊息

允許的 MIME 類型

範例指令碼

疑難排解

電子郵件傳遞

電子郵件節流

清除 Azure 通訊服務資源

下一步

意見反應

其他資源