Strapi Email provider for Azure Communication Service

Installation

1# using yarn
2yarn add strapi-provider-email-azure
3
4# using npm
5npm install strapi-provider-email-azure --save

Then in your config/plugins.js:

1module.exports = ({ env }) => ({
2  // ...
3  email: {
4    config: {
5      provider: 'strapi-provider-email-azure',
6      providerOptions: {
7        endpoint: env('AZURE_ENDPOINT'),
8      },
9      settings: {
10        defaultFrom: env('FALLBACK_EMAIL'),
11      },
12    },
13  },
14  // ...
15});

Usage

1await strapi
2  .plugin('email')
3  .service('email')
4  .send({
5    from: process.env.EMAIL_SERVICE_ADDRESS,
6    to: [
7      {
8        address: 'recipent@email.address',
9        displayName: 'Display Name',
10      },
11    ],
12    subject: 'Hello world',
13    text: 'Hello world',
14  });

You can also leave the from field empty to send the email from the fallback address.

The following fields are supported:

Field	Description
from	Email address of the sender (string)
to	Array of recipients (string | EmailAddress | Array<EmailAddress>)
cc	Array of recipients who get cc (string | EmailAddress | Array<EmailAddress>)
bcc	Array of recipients who get bcc (string | EmailAddress | Array<EmailAddress>)
replyTo	Email address to which replies are sent (Array<EmailAddress>)
subject	Subject of the email (string)
text	Plaintext version of the message (string)
html	HTML version of the message (string)
attachments	Array of attachments (Array<Attachment>)
disableUserEngagementTracking	Whether user engagement tracking should be disabled (boolean)
headers	Custom email headers (Dictionary<string, string>)

1type EmailAddress {
2    address: string,
3    displayName: string
4}
5type Attachment {
6    name: string,
7    contentType: string,
8    contentInBase64: string
9}

For more information, please refer to @azure/communication-email documentations:

• npm
• EmailMessage interface

How to create Azure Communication Service

1. Create the Email Communications Service

1. Navigate to the Azure portal to create a new resource
2. Create Email Communication Services
3. Complete the required information on the basics tab
4. Review the resource details. Click Create
5. Wait for the Deployment to complete

2. Create Communication Service

1. Navigate to the Azure portal to create a new resource
2. Create Communication Services
3. Complete the required information on the basics tab
4. Review the resource details. Click Create
5. Wait for the Deployment to complete

3. Connect the services

1. Go to your newly created Email Communcation Services resource, and navigate to Provision Domains
2. Add a new Azure managed domain or Custom domain
3. Go to your Communication Services resource, and navigate to Email/Domains
4. Connect to the domain you created in you Email Communication Services resource

4. Acquire access endpoint key

1. In your Communication Services resource, navigate to Settings/Keys
2. Copy your Primary key/Connection string
3. Store it in your environment variables
   AZURE_ENDPOINT=<connection_string>

5. (Optional) Create email addresses

1. In your Email Communication Services resource, go to Provision Domains, and click on the name of your domain
2. In Email services/MailFrom addresses you can create additional email addresses
3. By default DoNotReply@yourdomain is created, and you can store it as the fallback email address of strapi-provider-email-azure in your environment variables
   FALLBACK_EMAIL=DoNotReply@yourdomain

6. (Optional) Managed Identity if running on Azure instances

Create and assign an identity

1. Refer https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp on creating and managing identities.
2. Assign the identity to Azure Communication Service with the role 'Communication and Email Service Owner' or create a custom role definition to restrict the permissions.

Update plugins.js

Then in your config/plugins.js:

1module.exports = ({ env }) => ({
2  // ...
3  email: {
4    config: {
5      provider: 'strapi-provider-email-azure',
6      providerOptions: {
7        endpoint: env('AZURE_ENDPOINT'), // ex: https://<your-resource-name>-acsendpoint.<your-resource-location>.communication.azure.com
8        useManagedIdentity: true,
9        identityClientId: env('IDENTITY_CLIENT_ID') // GUID from the identity, ex : cf5c7b28-9eaa-47a1-b313-xxxxxxx
10      },
11      settings: {
12        defaultFrom: env('FALLBACK_EMAIL'),
13      },
14    },
15  },
16  // ...
17});