Azure Communication Email client library for Java - version 1.0.18

Article
10/28/2024

This package contains the Java SDK for Azure Communication Services for Email.

Getting started

Prerequisites

Azure subscription
Communication Service Resource
Email Communication Resource with an active Domain
Java Development Kit (JDK) version 8 or above
Apache Maven

To create these resources, you can use the Azure Portal, the Azure PowerShell, or the .NET management client library.

Include the package

Include the BOM file

Please include the azure-sdk-bom to your project to take dependency on the General Availability (GA) version of the library. In the following snippet, replace the {bom_version_to_target} placeholder with the version number. To learn more about the BOM, see the AZURE SDK BOM README.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

and then include the direct dependency in the dependencies section without the version tag.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-email</artifactId>
  </dependency>
</dependencies>

Include direct dependency

If you want to take dependency on a particular version of the library that is not present in the BOM, add the direct dependency to your project as follows.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-email</artifactId>
    <version>1.0.18</version>
</dependency>

Key concepts

More details coming soon.

Examples

EmailClient provides the functionality to send email messages .

Client Creation and Authentication

Email clients can be created and authenticated using the connection string acquired from an Azure Communication Resource in the Azure Portal.

String connectionString = "https://<resource-name>.communication.azure.com/;<access-key>";

EmailClient emailClient = new EmailClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Email clients can also be created and authenticated using the endpoint and Azure Key Credential acquired from an Azure Communication Resource in the Azure Portal.

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

EmailClient emailClient = new EmailClientBuilder()
    .endpoint(endpoint)
    .credential(azureKeyCredential)
    .buildClient();

Azure Active Directory Token Authentication

A DefaultAzureCredential object must be passed to the EmailClientBuilder via the credential() method. An endpoint must also be set via the endpoint() method.

The AZURE_CLIENT_SECRET, AZURE_CLIENT_ID, and AZURE_TENANT_ID environment variables are needed to create a DefaultAzureCredential object.

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

Send an Email Message

To send an email message, call the beginSend function from the EmailClient. This will return a poller. You can use this poller to check on the status of the operation and retrieve the result once it's finished.

EmailMessage message = new EmailMessage()
    .setSenderAddress("<sender-email-address>")
    .setToRecipients("<recipient-email-address>")
    .setSubject("test subject")
    .setBodyPlainText("test message");

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

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

Send an Email Message to Multiple Recipients

To send an email message to multiple recipients, simply add the new addresses in the appropriate EmailMessage setter.

EmailMessage message = new EmailMessage()
    .setSenderAddress("<sender-email-address>")
    .setSubject("test subject")
    .setBodyPlainText("test message")
    .setToRecipients("<recipient-email-address>", "<recipient-2-email-address>")
    .setCcRecipients("<cc-recipient-email-address>")
    .setBccRecipients("<bcc-recipient-email-address>");

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

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

To customize the email message recipients further, you can instantiate the EmailAddress objects and pass that them to the appropriate `EmailMessage' setters.

EmailAddress toAddress1 = new EmailAddress("<recipient-email-address>")
    .setDisplayName("Recipient");

EmailAddress toAddress2 = new EmailAddress("<recipient-2-email-address>")
    .setDisplayName("Recipient 2");

EmailMessage message = new EmailMessage()
    .setSenderAddress("<sender-email-address>")
    .setSubject("test subject")
    .setBodyPlainText("test message")
    .setToRecipients(toAddress1, toAddress2);

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

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

Send Email with Attachments

Azure Communication Services support sending email with attachments.

BinaryData attachmentContent = BinaryData.fromFile(new File("C:/attachment.txt").toPath());
EmailAttachment attachment = new EmailAttachment(
    "attachment.txt",
    "text/plain",
    attachmentContent
);

EmailMessage message = new EmailMessage()
    .setSenderAddress("<sender-email-address>")
    .setToRecipients("<recipient-email-address>")
    .setSubject("test subject")
    .setBodyPlainText("test message")
    .setAttachments(attachment);

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

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

Troubleshooting

More details coming soon,

Next steps

Read more about Email in Azure Communication Services

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Share via