Share via

Azure Communication Email client library for JavaScript - version 1.1.0

This package contains a JavaScript/TypeScript SDK for Azure Communication Services for Email.

Getting started

Prerequisites

You need an Azure subscription, a Communication Service Resource, and an Email Communication Resource with an active Domain.

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

Installing

npm install @azure/communication-email

Examples

EmailClient provides the functionality to send email messages.

Authentication

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

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

const connectionString = `endpoint=https://<resource-name>.communication.azure.com/;accessKey=<Base64-Encoded-Key>`;
const client = new EmailClient(connectionString);

You can also authenticate with Azure Active Directory using the Azure Identity library. To use the DefaultAzureCredential provider shown below, or other credential providers provided with the Azure SDK, please install the @azure/identity package:

npm install @azure/identity

The @azure/identity package provides a variety of credential types that your application can use to do this. The README for @azure/identity provides more details and samples to get you started. AZURE_CLIENT_SECRET, AZURE_CLIENT_ID and AZURE_TENANT_ID environment variables are needed to create a DefaultAzureCredential object.

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

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

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.

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

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

const message = {
  senderAddress: "[email protected]",
  content: {
    subject: "This is the subject",
    plainText: "This is the body",
  },
  recipients: {
    to: [
      {
        address: "[email protected]",
        displayName: "Customer Name",
      },
    ],
  },
};

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

Send an Email Message to Multiple Recipients

To send an email message to multiple recipients, add a object for each recipient type and an object for each recipient.

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

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

const message = {
  senderAddress: "[email protected]",
  content: {
    subject: "This is the subject",
    plainText: "This is the body",
  },
  recipients: {
    to: [
      {
        address: "[email protected]",
        displayName: "Customer Name 1",
      },
      {
        address: "[email protected]",
        displayName: "Customer Name 2",
      },
    ],
    cc: [
      {
        address: "[email protected]",
        displayName: " CC Customer 1",
      },
      {
        address: "[email protected]",
        displayName: "CC Customer 2",
      },
    ],
    bcc: [
      {
        address: "[email protected]",
        displayName: " BCC Customer 1",
      },
      {
        address: "[email protected]",
        displayName: "BCC Customer 2",
      },
    ],
  },
};

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

Send Email with Attachments

Azure Communication Services support sending email with attachments.

import { DefaultAzureCredential } from "@azure/identity";
import { EmailClient } from "@azure/communication-email";
import { basename } from "node:path";
import { readFileSync } from "node:fs";

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

const filePath = "path/to/readme.txt";

const message = {
  senderAddress: "[email protected]",
  content: {
    subject: "This is the subject",
    plainText: "This is the body",
  },
  recipients: {
    to: [
      {
        address: "[email protected]",
        displayName: "Customer Name",
      },
    ],
  },
  attachments: [
    {
      name: basename(filePath),
      contentType: "text/plain",
      contentInBase64: readFileSync(filePath, "base64"),
    },
  ],
};

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

Send Email with Inline Attachments

Azure Communication Services support sending email with inline attachments. Adding an optional contentId parameter to an attachment will make it an inline attachment.

import { DefaultAzureCredential } from "@azure/identity";
import { EmailClient } from "@azure/communication-email";
import { readFileSync } from "node:fs";

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

const imageBuffer = readFileSync("path/to/my_inline_image.jpg");
const contentInBase64 = imageBuffer.toString("base64");

const message = {
  senderAddress: "[email protected]",
  content: {
    subject: "This is the subject",
    plainText: "This is the body",
    html: '<html>This is the body<br /><img src="cid:inline_image" /></html>',
  },
  recipients: {
    to: [
      {
        address: "[email protected]",
        displayName: "Customer Name",
      },
    ],
  },
  attachments: [
    {
      name: "my_inline_image.jpg",
      contentType: "image/jpeg",
      contentInBase64: contentInBase64,
      contentId: "inline_image",
    },
  ],
};

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

Troubleshooting

Logging

Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL environment variable to info. Alternatively, logging can be enabled at runtime by calling setLogLevel in the @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Next steps

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 [email protected] with any additional questions or comments.