다음을 통해 공유

빠른 시작: Azure Communication Services를 사용하여 이메일을 보내는 방법

  • 아티클

이 빠른 시작에서는 이메일 SDK를 사용하여 이메일을 보내는 방법을 설명합니다.

Communication Services Try Email을 사용하여 이메일 메시지를 보내 Azure Communication Services를 시작합니다.

필수 조건

이 빠른 시작을 완료하면 Azure 계정에서 USD 센트 이하의 작은 비용이 발생합니다.

Try Email을 사용하여 이메일 보내기

Try Email을 사용하면 Azure Communication Services를 사용하여 원하는 수신자에게 이메일을 보내기를 시작하고 애플리케이션에서 이메일을 보낼 수 있는 구성을 확인할 수 있습니다. 또한 선호하는 언어의 코드 조각을 사용하여 이메일 알림 개발을 바로 시작하는 데 도움이 됩니다.

수신자에게 메시지를 보내고 메시지 제목과 본문을 지정하려면 다음을 수행합니다.

  1. 프로비전된 Azure Communication Service 리소스의 개요 페이지에서 이메일 아래의 왼쪽 탐색 패널에 있는 Try Email을 클릭합니다.

    이메일 사용해보기의 왼쪽 탐색 패널을 보여 주는 스크린샷.

  2. 드롭다운에서 확인된 도메인 중 하나를 선택합니다.

    드롭다운에서 확인된 도메인을 보여 주는 스크린샷

  3. 보낼 이메일 작성

    • 수신자 이메일 주소 입력
    • 제목 입력
    • 이메일 본문 작성

    연결할 확인된 메일 도메인 중 하나를 필터링하고 선택하는 방법을 보여 주는 스크린샷

  4. 페이지 맨 아래에 있는 보내기

    확인된 메일 도메인 중 하나가 이제 연결되어 있음을 보여 주는 스크린샷

  5. 이메일이 성공적으로 전송되었습니다.

    성공적인 이메일 전송을 보여 주는 스크린샷.

  6. 이제 샘플 코드 조각을 복사하여 샘플 프로젝트에서 알림을 보내는 데 사용할 이메일을 보낼 수도 있습니다.

    • 원하는 언어 선택

    • 내 연결 삽입 클릭

    • 복사 클릭

      이메일을 보내는 코드 조각을 보여 주는 스크린샷.

  7. 이제 알림 프로젝트에서 이메일 코드 조각을 사용할 준비가 되었습니다.

Azure CLI 커뮤니케이션 확장을 사용하여 이메일 메시지를 보내 Azure Communication Services를 시작합니다.

이 빠른 시작을 완료하면 Azure 계정에서 USD 센트 이하의 작은 비용이 발생합니다.

필수 조건

필수 구성 요소 확인

  • 터미널 또는 명령 창에서 az --version 명령을 실행하여 Azure CLI 및 커뮤니케이션 확장이 설치되어 있는지 확인합니다.
  • Email Communication Services 리소스로 확인된 도메인을 보려면 Azure portal에 로그인합니다. Email Communication Services 리소스를 찾아 왼쪽 탐색 창에서 도메인 프로비저닝 탭을 엽니다.

설정

확장 추가

az extension 명령을 사용하여 Azure CLI에 대한 Azure Communication Services 확장을 추가합니다.

az extension add --name communication

Azure CLI에 로그인

Azure CLI에 로그인해야 합니다. 터미널에서 az login 명령을 실행하고 자격 증명을 제공하여 로그인할 수 있습니다.

환경 변수에 연결 문자열 저장

--connection_string을 사용하여 연결 문자열을 전달하지 않고도 Azure CLI 키 작업을 사용하도록 AZURE_COMMUNICATION_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 Monitor 또는 Azure Event Grid를 통해 얻을 수 있습니다. 이메일 이벤트 구독 방법을 알아보세요.
실패함 이메일 보내기 작업이 성공하지 못했고 오류가 발생했습니다. 이메일이 발송되지 않았습니다. 결과에는 실패 이유에 대한 자세한 내용이 포함된 오류 개체가 포함됩니다.

선택적 매개 변수

다음 선택적 매개 변수는 Azure CLI에서 사용할 수 있습니다.

  • html 이메일 본문에 --text 대신 --html을 사용해도 됩니다.

  • --importance는 이메일의 중요도 유형을 설정합니다. 알려진 값은 높음, 보통 및 낮음입니다. 기본값은 보통입니다.

  • --to는 이메일 수신자 목록을 설정합니다.

  • --cc는 복사본 이메일 주소를 설정합니다.

  • --bcc는 복사본 이메일 주소를 가립니다.

  • --reply-to는 회신 이메일 주소를 설정합니다.

  • --disable-tracking은 이 요청에 대해 사용자 참여 추적을 사용하지 않도록 설정해야 하는지 여부를 나타냅니다.

  • --attachments는 이메일 첨부 파일 목록을 설정합니다.

  • --attachment-types는 이메일 첨부 파일 유형 목록을 동일한 첨부 파일 순서로 설정합니다.

또한 --to와 유사한 --cc 및 --bcc가 포함된 수신자 목록을 사용할 수 있습니다. --to, --cc 또는 --bcc에는 수신자가 하나 이상 있어야 합니다.

Communication Services C# 이메일 클라이언트 라이브러리를 사용하여 이메일 메시지를 보내 Azure Communication Services를 시작합니다.

팁

GitHub의 기본 이메일 전송 및 고급 이메일 전송 샘플 코드로 바로 건너뛰어 Azure Communication Services를 통해 이메일 전송 환경을 바로 시작합니다.

이메일 개체 모델 이해

다음 클래스 및 인터페이스는 C#용 Azure Communication Services 이메일 클라이언트 라이브러리의 주요 기능 중 일부를 처리합니다.

이름 설명
EmailAddress 이 클래스에는 이메일 주소와 표시 이름에 대한 옵션이 포함되어 있습니다.
EmailAttachment 이 클래스는 고유한 ID, 전자 메일 첨부 파일 MIME 형식 문자열, 콘텐츠에 대한 이진 데이터 및 인라인 첨부 파일로 정의하는 선택적 콘텐츠 ID를 수락하여 전자 메일 첨부 파일을 만듭니다.
EmailClient 이 클래스는 모든 이메일 기능에 필요합니다. 연결 문자열로 인스턴스화하고 이메일 메시지를 보내는 데 사용합니다.
EmailClientOptions 이 클래스는 특정 API 버전을 대상으로 하기 위해 EmailClient 인스턴스화에 추가될 수 있습니다.
EmailContent 이 클래스에는 이메일 메시지의 제목과 본문이 포함됩니다. PlainText 또는 Html 콘텐츠를 하나 이상 지정해야 합니다.
EmailCustomHeader 이 클래스를 사용하면 사용자 지정 헤더에 대한 이름 및 값 쌍을 추가할 수 있습니다. 헤더 이름 'x-priority' 또는 'x-msmail-priority'를 사용하여 이러한 헤더를 통해 이메일 중요도를 지정할 수도 있습니다.
EmailMessage 이 클래스는 보낸 사람, 콘텐츠 및 받는 사람을 결합합니다. 사용자 지정 헤더, 첨부 파일 및 회신 이메일 주소도 선택적으로 추가할 수 있습니다.
EmailRecipients 이 클래스는 참조 및 숨은 참조 수신자에 대한 선택적 목록을 포함하여 이메일 메시지 수신자에 대한 EmailAddress 개체 목록을 보유합니다.
EmailSendOperation 이 클래스는 비동기 이메일 보내기 작업을 나타내며 이메일 보내기 api 호출에서 반환됩니다.
EmailSendResult 이 클래스는 이메일 보내기 작업의 결과를 보관합니다. 작업 ID, 작업 상태 및 오류 개체(해당하는 경우)로 구성됩니다.

EmailSendResult는 수행된 이메일 작업에 대해 다음 상태 반환합니다.

상태 설명
NotStarted 지금은 서비스에서 이 상태를 보내지 않습니다.
실행 중 이메일 보내기 작업이 현재 진행 중이며 처리 중입니다.
성공 이메일 보내기 작업이 오류 없이 완료되었으며 이메일이 배달 중입니다. 이 단계 이후의 이메일 배달에 대한 자세한 상태는 Azure Monitor 또는 Azure Event Grid를 통해 얻을 수 있습니다. 이메일 이벤트 구독 방법을 알아보세요.
실패함 이메일 보내기 작업이 성공하지 못했고 오류가 발생했습니다. 이메일이 발송되지 않았습니다. 결과에는 실패 이유에 대한 자세한 내용이 포함된 오류 개체가 포함됩니다.

필수 조건

이 빠른 시작을 완료하면 Azure 계정에서 USD 센트 이하의 작은 비용이 발생합니다.

참고 항목

확인된 자체 도메인에서 이메일을 보낼 수도 있습니다. Email Communication Service에 확인된 사용자 지정 도메인 추가

필수 구성 요소 확인

  • 터미널 또는 명령 창에서 dotnet 명령을 실행하여 .NET 클라이언트 라이브러리가 설치되어 있는지 확인합니다.
  • Email Communication Services 리소스와 연결된 하위 도메인을 보려면 Azure Portal에 로그인하고 Email Communication Services 리소스를 찾은 다음 왼쪽 탐색 창에서 도메인 프로비저닝 탭을 엽니다.

새 C# 애플리케이션 만들기

콘솔 창(예: cmd, PowerShell 또는 Bash)에서 dotnet new 명령을 사용하여 EmailQuickstart라는 새 콘솔 앱을 만듭니다. 이 명령은 Program.cs라는 원본 파일 하나만 들어 있는 간단한 "Hello World" C# 프로젝트를 만듭니다.

dotnet new console -o EmailQuickstart

디렉터리를 새로 만든 앱 폴더로 변경하고 dotnet build 명령을 사용하여 애플리케이션을 컴파일합니다.

cd EmailQuickstart
dotnet build

패키지 설치

애플리케이션 디렉터리에 있는 동안 dotnet add package 명령을 사용하여 .NET 패키지용 Azure Communication Services 이메일 클라이언트 라이브러리를 설치합니다.

dotnet add package Azure.Communication.Email

인증을 사용하여 이메일 클라이언트 만들기

Program.cs를 열고 기존 코드를 다음으로 대체하여 Azure.Communication.Email 네임스페이스와 프로그램 실행 시작점을 포함하기 위한 using 지시문을 추가합니다.

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

using Azure;
using Azure.Communication.Email;

namespace SendEmail
{
  internal class Program
  {
    static async Task Main(string[] args)
    {

    }
  }
}

이메일 클라이언트를 인증하는 데 사용할 수 있는 몇 가지 옵션이 있습니다.

텍스트 편집기에서 Program.cs를 열고 Main 메서드의 본문을 코드로 바꿔 연결 문자열로 EmailClient를 초기화합니다. 다음 코드는 COMMUNICATION_SERVICES_CONNECTION_STRING이라는 환경 변수에서 리소스에 대한 연결 문자열을 검색합니다. 리소스의 연결 문자열을 관리하는 방법을 알아봅니다.

// This code demonstrates how to fetch your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
EmailClient emailClient = new EmailClient(connectionString);

참고 항목

이메일을 보내려면 수동 폴링(비동기 상태 폴링으로 이메일 보내기)을 사용하는 것이 좋습니다.

기본 이메일 보내기

이메일 메시지 작성

이메일 메시지를 보내려면 다음이 필요합니다.

  • 이메일 제목과 본문을 정의합니다.
  • 보낸 사람 주소를 정의합니다. 확인된 도메인에서 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";

이메일을 보내고 이메일 보내기 상태 받기

Azure.WaitUntil.Started를 사용하여 SendAsync를 호출하면 작업을 시작한 후 메서드가 다시 반환됩니다. 이 메서드는 EmailSendOperation 개체를 반환합니다. UpdateStatusAsync 메서드를 호출하여 이메일 작업 상태 새로 고칠 수 있습니다.

반환된 EmailSendOperation 개체에는 다음을 포함하는 EmailSendStatus 개체가 포함됩니다.

  • 이메일 보내기 작업의 현재 상태
  • 현재 상태가 실패인 경우 오류 세부 정보가 포함된 오류 개체

/// Send the email message with WaitUntil.Started
EmailSendOperation emailSendOperation = await emailClient.SendAsync(
    Azure.WaitUntil.Started,
    sender,
    recipient,
    subject,
    htmlContent);

/// Call UpdateStatus on the email send operation to poll for the status
/// manually.
try
{
    while (true)
    {
        await emailSendOperation.UpdateStatusAsync();
        if (emailSendOperation.HasCompleted)
        {
            break;
        }
        await Task.Delay(100);
    }

    if (emailSendOperation.HasValue)
    {
        Console.WriteLine($"Email queued for delivery. Status = {emailSendOperation.Value.Status}");
    }
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Email send failed with Code = {ex.ErrorCode} and Message = {ex.Message}");
}

/// Get the OperationId so that it can be used for tracking the message for troubleshooting
string operationId = emailSendOperation.Id;
Console.WriteLine($"Email operation id = {operationId}");

dotnet run 명령을 사용하여 애플리케이션 디렉터리에서 애플리케이션을 실행합니다.

dotnet run

샘플 코드

샘플 앱은 GitHub에서 다운로드할 수 있습니다.

Communication Services JS 이메일 클라이언트 라이브러리를 사용하여 이메일 메시지를 보내 Azure Communication Services를 시작합니다.

팁

GitHub의 기본 이메일 전송 및 고급 이메일 전송 샘플 코드로 바로 건너뛰어 Azure Communication Services를 통해 이메일 전송 환경을 바로 시작합니다.

이메일 개체 모델 이해

다음 클래스 및 인터페이스는 JavaScript용 Azure Communication Services 이메일 클라이언트 라이브러리의 주요 기능 중 일부를 처리합니다.

이름 설명
EmailAddress 이 클래스에는 이메일 주소와 표시 이름에 대한 옵션이 포함되어 있습니다.
EmailAttachment 이 클래스는 고유한 ID, 전자 메일 첨부 파일 MIME 형식 문자열, 콘텐츠에 대한 이진 데이터 및 인라인 첨부 파일로 정의하는 선택적 콘텐츠 ID를 수락하여 전자 메일 첨부 파일을 만듭니다.
EmailClient 이 클래스는 모든 이메일 기능에 필요합니다. 연결 문자열로 인스턴스화하고 이메일 메시지를 보내는 데 사용합니다.
EmailClientOptions 이 클래스는 특정 API 버전을 대상으로 하기 위해 EmailClient 인스턴스화에 추가될 수 있습니다.
EmailContent 이 클래스에는 이메일 메시지의 제목과 본문이 포함됩니다. PlainText 또는 Html 콘텐츠를 하나 이상 지정해야 합니다.
EmailCustomHeader 이 클래스를 사용하면 사용자 지정 헤더에 대한 이름 및 값 쌍을 추가할 수 있습니다. 헤더 이름 'x-priority' 또는 'x-msmail-priority'를 사용하여 이러한 헤더를 통해 이메일 중요도를 지정할 수도 있습니다.
EmailMessage 이 클래스는 보낸 사람, 콘텐츠 및 받는 사람을 결합합니다. 사용자 지정 헤더, 첨부 파일 및 회신 이메일 주소도 선택적으로 추가할 수 있습니다.
EmailRecipients 이 클래스는 참조 및 숨은 참조 수신자에 대한 선택적 목록을 포함하여 이메일 메시지 수신자에 대한 EmailAddress 개체 목록을 보유합니다.
EmailSendResult 이 클래스는 이메일 보내기 작업의 결과를 보관합니다. 작업 ID, 작업 상태 및 오류 개체(해당하는 경우)로 구성됩니다.
EmailSendStatus 이 클래스는 이메일 보내기 작업의 상태 세트를 나타냅니다.

EmailSendResult는 수행된 이메일 작업에 대해 다음 상태 반환합니다.

상태 이름 설명
isStarted 이메일 보내기 작업이 현재 진행 중이고 처리 중이면 true를 반환합니다.
isCompleted 이메일 보내기 작업이 오류 없이 완료되었고 이메일이 배달 중이면 true를 반환합니다. 이 단계 이후의 이메일 배달에 대한 자세한 상태는 Azure Monitor 또는 Azure Event Grid를 통해 얻을 수 있습니다. 이메일 이벤트 구독 방법을 알아보세요.
result 이메일 보내기 작업이 완료된 경우에 존재하는 속성입니다.
error 이메일 보내기 작업이 성공하지 못했고 오류가 발생한 경우에 존재하는 속성입니다. 이메일이 발송되지 않았습니다. 결과에는 실패 이유에 대한 자세한 내용이 포함된 오류 개체가 포함됩니다.

필수 조건

이 빠른 시작을 완료하면 Azure 계정에서 USD 센트 이하의 작은 비용이 발생합니다.

참고 항목

확인된 자체 도메인에서 이메일을 보낼 수도 있습니다. Email Communication Service에 확인된 사용자 지정 도메인 추가

필수 구성 요소 확인

  • 터미널 또는 명령 창에서 node --version를 실행하여 Node.js가 설치되어 있는지 확인합니다.
  • Email Communication Services 리소스로 확인된 도메인을 보려면 Azure Portal에 로그인하고 Email Communication Services 리소스를 찾은 다음 왼쪽 탐색 창에서 도메인 프로비저닝 탭을 엽니다.

애플리케이션 환경 설정

새 Node.js 애플리케이션 만들기

먼저 터미널 또는 명령 창을 열어 앱에 대한 새 디렉터리를 만들고 해당 디렉터리로 이동합니다.

mkdir email-quickstart && cd email-quickstart

npm init -y를 실행하여 기본 설정으로 package.json 파일을 만듭니다.

npm init -y

텍스트 편집기를 사용하여 프로젝트 루트 디렉터리에 send-email.js라는 파일을 만듭니다. package.json의 "main" 속성을 "send-email.js"로 변경합니다. 다음 섹션에서는 이 빠른 시작의 소스 코드를 새로 만든 파일에 추가하는 방법을 보여줍니다.

패키지 설치

npm install 명령을 사용하여 JavaScript용 Azure Communication Services 이메일 클라이언트 라이브러리를 설치합니다.

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에서 다운로드할 수 있습니다.

Communication Services Java Email SDK를 사용하여 Email 메시지를 보내 Azure Communication Services를 시작합니다.

팁

GitHub의 기본 이메일 전송 및 고급 이메일 전송 샘플 코드로 바로 건너뛰어 Azure Communication Services를 통해 이메일 전송 환경을 바로 시작합니다.

이메일 개체 모델 이해

다음 클래스 및 인터페이스는 Python용 Azure Communication Services Email SDK의 주요 기능 중 일부를 처리합니다.

이름 설명
EmailAddress 이 클래스에는 이메일 주소와 표시 이름에 대한 옵션이 포함되어 있습니다.
EmailAttachment 이 인터페이스는 고유한 ID, 전자 메일 첨부 파일 MIME 형식 문자열, 콘텐츠 바이트 문자열 및 인라인 첨부 파일로 정의하는 선택적 콘텐츠 ID를 수락하여 전자 메일 첨부 파일을 만듭니다.
EmailClient 이 클래스는 모든 이메일 기능에 필요합니다. 연결 문자열로 인스턴스화하고 이메일 메시지를 보내는 데 사용합니다.
EmailMessage 이 클래스는 보낸 사람, 콘텐츠 및 받는 사람을 결합합니다. 사용자 지정 헤더, 첨부 파일 및 회신 이메일 주소도 선택적으로 추가할 수 있습니다.
EmailSendResult 이 클래스는 이메일 보내기 작업의 결과를 보관합니다. 작업 ID, 작업 상태 및 오류 개체(해당하는 경우)로 구성됩니다.
EmailSendStatus 이 클래스는 이메일 보내기 작업의 상태 세트를 나타냅니다.

EmailSendResult는 수행된 이메일 작업에 대해 다음 상태 반환합니다.

상태 이름 설명
NOT_STARTED 지금은 서비스에서 이 상태를 보내지 않습니다.
IN_PROGRESS 이메일 보내기 작업이 현재 진행 중이며 처리 중입니다.
SUCCESSFULLY_COMPLETED 이메일 보내기 작업이 오류 없이 완료되었으며 이메일이 배달 중입니다. 이 단계 이후의 이메일 배달에 대한 자세한 상태는 Azure Monitor 또는 Azure Event Grid를 통해 얻을 수 있습니다. 이메일 이벤트 구독 방법을 알아보세요.
실패 이메일 보내기 작업이 성공하지 못했고 오류가 발생했습니다. 이메일이 발송되지 않았습니다. 결과에는 실패 이유에 대한 자세한 내용이 포함된 오류 개체가 포함됩니다.

필수 조건

이 빠른 시작을 완료하면 Azure 계정에서 USD 센트 이하의 작은 비용이 발생합니다.

참고 항목

확인된 자체 도메인에서 이메일을 보낼 수도 있습니다. Email Communication Service에 확인된 사용자 지정 도메인을 추가하세요.

필수 구성 요소 확인

  • 터미널 또는 명령 창에서 mvn -v를 실행하여 Maven이 설치되어 있는지 확인합니다.
  • Email Communication Services 리소스로 확인된 도메인을 보려면 Azure portal에 로그인합니다. Email Communication Services 리소스를 찾아 왼쪽 탐색 창에서 도메인 프로비저닝 탭을 엽니다.

애플리케이션 환경 설정

이메일을 보내기 위한 환경을 설정하려면 다음 섹션의 단계를 수행합니다.

새 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 주소로 바꿉니다.

이메일 메시지를 보내려면 EmailClient에서 beginSend 함수를 호출합니다.

동기화 클라이언트에서 beginSend를 호출하면 작업 상태를 확인하고 작업이 완료된 후 결과를 검색하는 데 사용할 수 있는 SyncPoller 개체가 반환됩니다. 이메일 전송을 위한 초기 요청은 beginSend 메서드가 호출되자마자 전송됩니다. 이메일 보내기는 장기간 실행되는 작업입니다. 폴러의 getFinalResult() 메서드는 최종 상태(SUCCESSFULLY_COMPLETED 또는 FAILED)에 도달할 때까지 차단 작업이라는 점에 유의해야 합니다. 권장되는 방법은 아래 샘플에 설명된 대로 애플리케이션 요구 사항에 적절한 간격으로 수동 폴링을 수행하는 것입니다.

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

    PollResponse<EmailSendResult> pollResponse = null;

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

    // Polling is done manually to avoid blocking the application in case of an error
    while (pollResponse == null
            || pollResponse.getStatus() == LongRunningOperationStatus.NOT_STARTED
            || pollResponse.getStatus() == LongRunningOperationStatus.IN_PROGRESS)
    {
        pollResponse = poller.poll();
        // The operation ID can be retrieved as soon as .poll() is called on the poller
        System.out.println("Email send poller status: " + pollResponse.getStatus() + ", operation id: " + pollResponse.getValue().getId());

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

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

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

코드 실행

  1. pom.xml 파일이 포함된 디렉터리로 이동하고 mvn 명령을 사용하여 프로젝트를 컴파일합니다.

    mvn compile

  2. 패키지를 빌드합니다.

    mvn package

  3. 다음 mvn 명령을 실행하여 앱을 실행합니다.

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

샘플 코드

샘플 앱은 GitHub에서 다운로드할 수 있습니다.

Communication Services Python Email SDK를 사용하여 Email 메시지를 보내 Azure Communication Services를 시작합니다.

팁

GitHub의 기본 이메일 전송 및 고급 이메일 전송 샘플 코드로 바로 건너뛰어 Azure Communication Services를 통해 이메일 전송 환경을 바로 시작합니다.

이메일 개체 모델 이해

다음 JSON 메시지 템플릿 및 응답 개체는 Python용 Azure Communication Services Email SDK의 주요 기능 중 일부를 보여줍니다.

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

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

response.status 값은 다음 표에 자세히 설명되어 있습니다.

상태 이름 설명
InProgress 이메일 보내기 작업이 현재 진행 중이며 처리 중입니다.
성공 이메일 보내기 작업이 오류 없이 완료되었으며 이메일이 배달 중입니다. 이 단계 이후의 이메일 배달에 대한 자세한 상태는 Azure Monitor 또는 Azure Event Grid를 통해 얻을 수 있습니다. 이메일 이벤트 구독 방법을 알아보세요.
실패함 이메일 보내기 작업이 성공하지 못했고 오류가 발생했습니다. 이메일이 발송되지 않았습니다. 결과에는 실패 이유에 대한 자세한 내용이 포함된 오류 개체가 포함됩니다.

필수 조건

이 빠른 시작을 완료하면 Azure 계정에서 USD 센트 이하의 작은 비용이 발생합니다.

참고 항목

확인된 자체 도메인에서 이메일을 보낼 수도 있습니다. Email Communication Service에 확인된 사용자 지정 도메인 추가

필수 구성 요소 확인

  • 터미널 또는 명령 창에서 python --version 명령을 실행하여 Python이 설치되어 있는지 확인합니다.
  • Email Communication Services 리소스로 확인된 도메인을 보려면 Azure portal에 로그인합니다. Email Communication Services 리소스를 찾아 왼쪽 탐색 창에서 도메인 프로비저닝 탭을 엽니다.

애플리케이션 환경 설정

이메일을 보내기 위한 환경을 설정하려면 다음 섹션의 단계를 수행합니다.

새 Python 애플리케이션 만들기

  1. 터미널 또는 명령 창을 엽니다. 그리고 다음 명령을 사용하여 가상 환경을 만들고 활성화합니다. 이 명령은 앱의 새 디렉터리를 만듭니다.

    python -m venv email-quickstart

  2. 가상 환경의 루트 디렉터리로 이동한 후 다음 명령을 사용하여 활성화합니다.

    cd email-quickstart
.\Scripts\activate

  3. 텍스트 편집기를 사용하여 프로젝트 루트 디렉터리에 send-email.py라는 파일을 만들고 기본 예외 처리를 비롯한 프로그램의 구조를 추가합니다.

    import os
from azure.communication.email import EmailClient

try:
    # Quickstart code goes here.
except Exception as ex:
    print('Exception:')
    print(ex)

다음 섹션에서는 이 빠른 시작의 모든 소스 코드를 앞에서 만든 send-email.py 파일에 추가합니다.

패키지 설치

여전히 애플리케이션 디렉터리에 있는 동안 다음 명령을 사용하여 Python용 Azure Communication Services Email SDK 패키지를 설치합니다.

pip install azure-communication-email

인증을 사용하여 이메일 클라이언트 만들기

이메일 클라이언트를 인증하는 데 사용할 수 있는 몇 가지 옵션이 있습니다.

연결 문자열로 EmailClient를 인스턴스화합니다. 리소스의 연결 문자열을 관리하는 방법을 알아봅니다.

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

편의상 이 빠른 시작에서는 연결 문자열을 사용하지만 프로덕션 환경에서는 서비스 주체를 사용하는 것이 좋습니다.

기본 이메일 보내기

이메일 메시지 보내기

이메일 메시지를 보내려면 다음이 필요합니다.

  • 다음 값을 사용하여 메시지를 작성합니다.
    • senderAddress: 유효한 보낸 사람 이메일 주소입니다. Email Communication Services 리소스에 연결된 도메인의 개요 창에 있는 MailFrom 필드에서 찾을 수 있습니다.
    • recipients: 이메일 수신자 목록과 필요에 따라 참조 및 숨은 참조 이메일 수신자 목록이 포함된 개체입니다.
    • 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 Communication Services 이메일 커넥터를 사용하여 워크플로에 새 단계를 추가하려면 다음 단계를 수행합니다.

  1. 디자이너에서 논리 앱 워크플로를 엽니다.

    소비

    1. 새 작업을 추가하려는 단계에서 새 단계를 선택합니다. 또는 새 작업을 단계 사이에 추가하려면 포인터를 해당 단계 사이의 화살표 위로 이동하고, 더하기 기호(+)를 선택한 다음, 작업 추가를 선택합니다.

    2. 작업 선택 검색 상자에서 프리미엄을 선택합니다. 검색 상자에 Azure 커뮤니케이션 이메일을 입력합니다.

    3. 작업 목록에서 이메일 보내기를 선택합니다.

      Azure Communication Services Email 커넥터 [이메일 보내기] 작업을 보여주는 스크린샷.

    Standard

    1. 새 작업을 추가하려는 단계에서 더하기 기호(+)를 선택합니다. 또는 새 작업을 단계 사이에 추가하려면 포인터를 해당 단계 사이의 화살표 위로 이동하고, 더하기 기호(+)를 선택한 다음, 작업 추가를 선택합니다.

    2. 작업 추가 검색 상자 아래 런타임 드롭다운에서 프리미엄을 선택합니다. 검색 상자에 Azure 커뮤니케이션 이메일을 입력합니다.

    3. 작업 목록에서 이메일 보내기를 선택합니다.

  2. 연결 이름을 제공합니다.

  3. Azure Communications Service 리소스에 대한 연결 문자열을 입력합니다. 이 문자열을 찾으려면 다음 단계를 수행합니다.

    1. Azure Portal에서 Communication Service 리소스를 엽니다.

    2. 리소스 메뉴의 설정 아래에서 키를 선택하고 연결 문자열을 복사합니다.

      Azure Communication Services 연결 문자열을 보여주는 스크린샷.

  4. 완료되면 만들기를 선택합니다.

  5. 보낸 사람 필드에서 필수 구성 요소에서 구성한 이메일 주소를 사용합니다. 받는 사람, 제목 및 본문 필드에 다음과 같이 입력합니다.

    Azure Communication Services Email 커넥터 [이메일 보내기] 작업 입력을 보여주는 스크린샷.

  6. 워크플로를 저장합니다. 디자이너 도구 모음에서 저장을 선택합니다.

워크플로 테스트

사용량 또는 표준 워크플로가 있는지 여부에 따라 워크플로를 수동으로 시작합니다.

  • 사용량: 디자이너 도구 모음에서 트리거 실행>실행을 선택합니다.
  • 표준: 워크플로 메뉴에서 개요를 선택합니다. 도구 모음에서 트리거 실행>실행을 선택합니다.

워크플로는 사용자를 만들고 해당 사용자에 대한 액세스 토큰을 발급한 다음, 사용자를 제거 및 삭제합니다. 워크플로가 성공적으로 실행된 후 이러한 작업의 출력을 확인할 수 있습니다.

지정된 주소에서 이메일을 받아야 합니다. 또한 이메일 메시지 상태 가져오기 작업을 사용하여 이메일 보내기 작업을 통해 보내는 이메일의 상태를 검사할 수 있습니다. 추가 작업을 보려면 Azure Communication Services Email 커넥터 참조 설명서를 검토하세요.

워크플로 리소스 정리

논리 앱 리소스, 워크플로 및 관련 리소스를 정리하려면 사용량 논리 앱 리소스를 정리하는 방법 또는 표준 논리 앱 리소스를 정리하는 방법을 검토하세요.

문제 해결

이메일 배달

이메일 배달과 관련된 문제를 해결하기 위해 이메일 배달 상태를 확인하여 배달 세부 정보를 캡처할 수 있습니다.

Important

전송 작업 상태에 대한 폴링을 통해 반환된 성공 결과는 이메일이 성공적으로 전송되었다는 팩트만 유효성 검사합니다. 수신자의 배달 상태에 대한 추가 정보를 가져오려면 이메일 이벤트 처리 방법을 참조해야 합니다.

이메일 제한

애플리케이션이 중단된 것으로 확인되면 이메일 보내기가 제한된 것일 수 있습니다. 로깅을 통해 또는 사용자 지정 정책을 구현하여 이 문제를 해결할 수 있습니다.

참고 항목

이 샌드박스 설정은 개발자가 애플리케이션 빌드를 시작하는 데 도움이 됩니다. 애플리케이션을 라이브로 전환할 준비가 되면 전송 볼륨을 늘리도록 점진적으로 요청할 수 있습니다. 속도 제한을 초과하는 메시지 볼륨을 보내야 하는 경우 원하는 전송 제한을 높이기 위해 지원 요청을 제출합니다.

Azure Communication Service 리소스 정리

Communication Services 구독을 정리하고 제거하려면 리소스 또는 리소스 그룹을 삭제하면 됩니다. 리소스 그룹을 삭제하면 연결된 다른 리소스도 삭제됩니다. 리소스 정리에 대해 자세히 알아보세요.

다음 단계

이 빠른 시작에서는 Azure Communication Services를 사용하여 이메일을 보내는 방법을 알아보았습니다. 다음을 수행할 수도 있습니다.