Azure Communication Services

Sending Emails with Azure Communication Services

This document provides a comprehensive guide to using the Azure Communication Services JavaScript SDK to send emails. Leverage the power of Azure to send transactional and marketing emails programmatically.

Prerequisites

• An Azure subscription.
• An Azure Communication Services resource.
• The Azure Communication Services JavaScript SDK installed in your project. You can install it using npm:

  npm install @azure/communication-email

• A valid connection string for your Azure Communication Services resource.

Getting Started

To begin sending emails, you need to initialize the EmailClient with your resource's connection string.

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

// Replace with your actual connection string
const connectionString = "YOUR_ACS_CONNECTION_STRING";
const credential = new AzureKeyCredential(connectionString);

const emailClient = new EmailClient(credential);
        

Sending a Simple Email

The core functionality for sending emails is provided by the send method of the EmailClient.

async function sendBasicEmail() {
    const emailMessage = {
        sender: "do-not-reply@YOUR_DOMAIN.com", // Replace with your verified sender domain
        content: {
            plainText: "This is a test email sent from Azure Communication Services.",
            html: "<h1>Welcome!</h1><p>This is a test email sent from Azure Communication Services.</p>"
        },
        recipients: {
            to: ["recipient1@example.com", "recipient2@example.com"],
            // cc: ["cc1@example.com"],
            // bcc: ["bcc1@example.com"]
        },
        subject: "Test Email from ACS JavaScript SDK"
    };

    try {
        const response = await emailClient.send(emailMessage);
        console.log("Email sent successfully:", response);
    } catch (error) {
        console.error("Error sending email:", error);
    }
}

sendBasicEmail();
            

Advanced Features

Attachments

You can include attachments in your emails. Each attachment object should have a name and contentType, along with the content in base64 encoded format.

// Example attachment
const attachment = {
    name: "report.pdf",
    contentType: "application/pdf",
    content: "JVBERi0xLjcKJeLTgjcgo..." // Base64 encoded content of your PDF
};

const emailMessageWithAttachment = {
    sender: "sender@YOUR_DOMAIN.com",
    content: {
        plainText: "Please find the attached report.",
        html: "<p>Please find the attached report.</p>"
    },
    recipients: {
        to: ["recipient@example.com"]
    },
    subject: "Email with Attachment",
    attachments: [attachment]
};
// ... then send using emailClient.send(emailMessageWithAttachment)
        

Custom Headers

You can add custom headers to your emails for tracking or other purposes.

const emailMessageWithHeaders = {
    sender: "sender@YOUR_DOMAIN.com",
    content: {
        plainText: "Email with custom headers.",
        html: "<p>Email with custom headers.</p>"
    },
    recipients: {
        to: ["recipient@example.com"]
    },
    subject: "Custom Headers Example",
    headers: {
        "X-Custom-Header": "MyValue"
    }
};
// ... then send using emailClient.send(emailMessageWithHeaders)
        

Error Handling

Always implement robust error handling to manage potential issues during email sending. The SDK throws exceptions for various error scenarios, such as invalid sender addresses, network problems, or authentication failures.

Key Considerations

• Sender Verification: Ensure that your sender email domain is properly verified within your Azure Communication Services resource.
• Rate Limits: Be mindful of any API rate limits imposed by Azure Communication Services.
• Asynchronous Operations: The send method is asynchronous. Use async/await or Promises to handle the response.
• Security: Never expose your connection string directly in client-side code. Use a secure backend to manage credentials and interact with the SDK.