Quickstart: Manage domain suppression lists in Azure Communication Services using the management client libraries

Important

Functionality described in this article is currently in public preview. This preview version is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

This quick start covers the process for managing domain suppression lists in Azure Communication Services using the Azure Communication Services management client libraries.

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• An Azure Email Communication Services Resource ready to provision domains. Get started creating an Email Communication Resource.
• An Azure Managed Domain or Custom Domain provisioned and ready to send emails.
• We're using a service principal for authentication. Set the values of the client ID, tenant ID, and client secret of the Azure Active Directory (AD) application as the following environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET.

Install the required packages

dotnet add package Azure.ResourceManager.Communication
dotnet add package Azure.Identity

Initialize the management client

Set the environment variable AZURE_SUBSCRIPTION_ID with the subscription ID of the subscription your Domain and Email resources are in. Run the code sample to initialize the management client.

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Communication;

ArmClient client = new ArmClient(new DefaultAzureCredential());

Add a suppression list to a domain resource

To block your email messages from being sent to certain addresses, the first step is setting up a suppression list in your domain resource.

Update the code sample with the resource group name, the email service name, and the domain resource name for which you would like to create the suppression list. Find this information in the portal by navigating to the domain resource you created when setting up the prerequisites. The title of the resource is <your-email-service-name>/<your-domain-name>. Find the resource group name and subscription ID in the Essentials sections in the domain resource overview. Choose any name for your suppression list resource and update that field in the sample as well.

For the list name, make sure it's the same as the sender username of the MailFrom address you would like to suppress emails from. These MailFrom addresses can be found in the "MailFrom addresses" section of your domain resource in the portal. For example, you may have a MailFrom address that looks like "donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net". The sender username for this address would be "donotreply" so a list name of "donotreply" should be used.

The code sample will create the suppression list and store it in the suppressionListResource variable for future operations.

string subscriptionId = "<your-subscription-id>"; // Found in the essentials section of the domain resource portal overview
string resourceGroupName = "<your-resource-group-name>"; // Found in the essentials section of the domain resource portal overview
string emailServiceName = "<your-email-service-name>"; // Found in the first part of the portal domain resource title
string domainResourceName = "<your-domain-name>"; // Found in the second part of the portal domain resource title
string suppressionListResourceName = "<your-suppression-list-resource-name>";

ResourceIdentifier suppressionListResourceId = SuppressionListResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, emailServiceName, domainResourceName, suppressionListResourceName);
SuppressionListResource suppressionListResource = client.GetSuppressionListResource(suppressionListResourceId);

SuppressionListResourceData suppressionListData = new SuppressionListResourceData()
{
    ListName = "<your-sender-username>", // Should match the sender username of the MailFrom address you would like to suppress emails from
};

suppressionListResource.Update(WaitUntil.Completed, suppressionListData);

If you would like to suppress emails from all the sender usernames in particular domain, you can pass in an empty string for the list name.

SuppressionListResourceData suppressionListData = new SuppressionListResourceData()
{
    ListName = "",
};

suppressionListResource.Update(WaitUntil.Completed, suppressionListData);

Add an address to a suppression list

After setting up the suppression list, you can now add specific email addresses to which you wish to prevent your email messages from being sent.

Update the code sample with the suppression list address ID. Every suppression list address ID you add needs to be unique. We recommend using a GUID. Update the email address you want to block from receiving your messages as well.

To add multiple addresses to the suppression list, you need to repeat this code sample multiple times.

string suppressionListAddressId = "<your-suppression-list-address-id>";

ResourceIdentifier suppressionListAddressResourceId = SuppressionListAddressResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, emailServiceName, domainResourceName, suppressionListResourceName, suppressionListAddressId);
SuppressionListAddressResource suppressionListAddressResource = client.GetSuppressionListAddressResource(suppressionListAddressResourceId);

SuppressionListAddressResourceData suppressionListAddressData = new SuppressionListAddressResourceData()
{
    Email = "<email-address-to-suppress>" // Should match the email address you would like to block from receiving your messages
};

suppressionListAddressResource.Update(WaitUntil.Completed, suppressionListAddressData);

You can now try sending an email to the suppressed address from the TryEmail section of your Communication Service resource or by using one of the Email SDKs. Make sure to send the email using the MailFrom address with the sender username you've chosen to suppress. Your email won't send to the suppressed address.

If you try sending an email from a sender username that is not suppressed the email still successfully sends.

Remove an address from a suppression list

To remove an address from the suppression list, create the SuppressionListAddressResource as shown in the previous code samples and call the Delete method.

suppressionListAddressResource.Delete(WaitUntil.Completed);

You can now try sending an email to the suppressed address from the TryEmail section of your Communication Service resource or by using one of the Email SDKs. Make sure to send the email using the MailFrom address with the sender username you choose to suppress. Your email will successfully send to the previously suppressed address.

Remove a suppression list from a domain resource

To remove a suppression list from the domain resource, create the SuppressionListResource as shown in the previous code samples and call the Delete method.

suppressionListResource.Delete(WaitUntil.Completed);

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• An Azure Email Communication Services Resource ready to provision domains. Get started creating an Email Communication Resource.
• An Azure Managed Domain or Custom Domain provisioned and ready to send emails.
• We're using a service principal for authentication. Set the values of the client ID, tenant ID, and client secret of the Azure Active Directory (AD) application as the following environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET.

Install the required packages

npm install @azure/arm-communication
npm install @azure/identity

Initialize the management client

Replace the field in the sample code with the subscription ID of the subscription your Domain and Email resources are in. Run the code sample to initialize the management client.

const { CommunicationServiceManagementClient } = require("@azure/arm-communication");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const subscriptionId = "<your-subscription-id>";

const client = new CommunicationServiceManagementClient(credential, subscriptionId);

Add a suppression list to a domain resource

To block your email messages from being sent to certain addresses, the first step is setting up a suppression list in your domain resource.

Update the code sample with the resource group name, the email service name, and the domain resource name for which you would like to create the suppression list. Find this information in the portal by navigating to the domain resource you created when setting up the prerequisites. The title of the resource is <your-email-service-name>/<your-domain-name>. Find the resource group name and subscription ID in the Essentials sections in the domain resource overview. Choose any name for your suppression list resource and update that field in the sample as well.

For the list name, make sure it's the same as the sender username of the MailFrom address you would like to suppress emails from. These MailFrom addresses can be found in the "MailFrom addresses" section of your domain resource in the portal. For example, you may have a MailFrom address that looks like "donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net". The sender username for this address would be "donotreply" so a list name of "donotreply" should be used.

const resourceGroupName = "<your-resource-group-name>"; // Found in the essentials section of the domain resource portal overview
const emailServiceName = "<your-email-service-name>"; // Found in the first part of the portal domain resource title
const domainResourceName = "<your-domain-name>"; // Found in the second part of the portal domain resource title
const suppressionListResourceName = "<your-suppression-list-resource-name>";

parameters = { 
    "listName": "<your-sender-username>", // Should match the sender username of the MailFrom address you would like to suppress emails from
}

await client.suppressionLists.createOrUpdate(
    resourceGroupName,
    emailServiceName,
    domainResourceName,
    suppressionListResourceName,
    parameters
);

If you would like to suppress emails from all the sender usernames in particular domain, you can pass in an empty string for the list name.

parameters = { 
    "listName": "",
}

await client.suppressionLists.createOrUpdate(
    resourceGroupName,
    emailServiceName,
    domainResourceName,
    suppressionListResourceName,
    parameters
);

Add an address to a suppression list

After setting up the suppression list, you can now add specific email addresses to which you wish to prevent your email messages from being sent.

Update the code sample with the suppression list address ID. Every suppression list address ID you add needs to be unique. We recommend using a GUID. Update the email address you want to block from receiving your messages as well.

To add multiple addresses to the suppression list, you need to repeat this code sample multiple times.

const suppressionListAddressId = "<your-suppression-list-address-id>";

parameters = { 
    "email": "<email-address-to-suppress>" // Should match the email address you would like to block from receiving your messages
}

await client.suppressionListAddresses.createOrUpdate(
    resourceGroupName,
    emailServiceName,
    domainResourceName,
    suppressionListResourceName,
    suppressionListAddressId,
    parameters
);

You can now try sending an email to the suppressed address from the TryEmail section of your Communication Service resource or by using one of the Email SDKs. Make sure to send the email using the MailFrom address with the sender username you've chosen to suppress. Your email won't send to the suppressed address.

If you try sending an email from a sender username that is not suppressed the email still successfully sends.

Remove an address from a suppression list

Call the delete method on suppressionListAddresses to remove an address from the suppression list.

await client.suppressionListAddresses.delete(
    resourceGroupName,
    emailServiceName,
    domainResourceName,
    suppressionListResourceName,
    suppressionListAddressId
);

You can now try sending an email to the suppressed address from the TryEmail section of your Communication Service resource or by using one of the Email SDKs. Make sure to send the email using the MailFrom address with the sender username you choose to suppress. Your email will successfully send to the previously suppressed address.

Remove a suppression list from a domain resource

Call the delete method on suppressionList to remove a suppression list from the domain resource.

await client.suppressionLists.delete(
    resourceGroupName,
    emailServiceName,
    domainResourceName,
    suppressionListResourceName
);

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• An Azure Email Communication Services Resource ready to provision domains. Get started creating an Email Communication Resource.
• An Azure Managed Domain or Custom Domain provisioned and ready to send emails.
• We're using a service principal for authentication. Set the values of the client ID, tenant ID, and client secret of the Azure Active Directory (AD) application as the following environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET.

Install the required packages

Add the following dependencies to your pom.xml.

<dependency>
    <groupId>com.azure.resourcemanager</groupId>
    <artifactId>azure-resourcemanager-communication</artifactId>
    <version>2.2.0</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.11.1</version>
</dependency>

Initialize the management client

Set the environment variable AZURE_SUBSCRIPTION_ID with the subscription ID of the subscription your Domain and Email resources are in.

Add the following imports at the top of your file.

import com.azure.core.credential.TokenCredential;
import com.azure.core.management.AzureEnvironment;
import com.azure.core.management.profile.AzureProfile;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.resourcemanager.communication.CommunicationManager;

Run the code sample to initialize the management client.

AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
TokenCredential credential = new DefaultAzureCredentialBuilder()
        .authorityHost(profile.getEnvironment().getActiveDirectoryEndpoint())
        .build();

CommunicationManager manager = CommunicationManager
        .authenticate(credential, profile);

Add a suppression list to a domain resource

To block your email messages from being sent to certain addresses, the first step is setting up a suppression list in your domain resource.

Update the code sample with the resource group name, the email service name, and the domain resource name for which you would like to create the suppression list. Find this information in the portal by navigating to the domain resource you created when setting up the prerequisites. The title of the resource is <your-email-service-name>/<your-domain-name>. Find the resource group name and subscription ID in the Essentials sections in the domain resource overview. Choose any name for your suppression list resource and update that field in the sample as well.

For the list name, make sure it's the same as the sender username of the MailFrom address you would like to suppress emails from. These MailFrom addresses can be found in the "MailFrom addresses" section of your domain resource in the portal. For example, you may have a MailFrom address that looks like "donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net". The sender username for this address would be "donotreply" so a list name of "donotreply" should be used.

String resourceGroupName = "<your-resource-group-name>"; // Found in the essentials section of the domain resource portal overview
String emailServiceName = "<your-email-service-name>"; // Found in the first part of the portal domain resource title
String domainResourceName = "<your-domain-name>"; // Found in the second part of the portal domain resource title
String suppressionListResourceName = "<your-suppression-list-resource-name>";

manager.suppressionLists().define(suppressionListResourceName)
    .withExistingDomain(resourceGroupName, emailServiceName, domainResourceName)
    .withListName("<your-sender-username>") // Should match the sender username of the MailFrom address you would like to suppress emails from
    .create();

If you would like to suppress emails from all the sender usernames in particular domain, you can pass in an empty string for the list name.

manager.suppressionLists().define(suppressionListResourceName)
    .withExistingDomain(resourceGroupName, emailServiceName, domainResourceName)
    .withListName("")
    .create();

Add an address to a suppression list

After setting up the suppression list, you can now add specific email addresses to which you wish to prevent your email messages from being sent.

Update the code sample with the suppression list address ID. Every suppression list address ID you add needs to be unique. We recommend using a GUID. Update the email address you want to block from receiving your messages as well.

To add multiple addresses to the suppression list, you need to repeat this code sample multiple times.

String suppressionListAddressId = "<your-suppression-list-address-id>";

manager.suppressionListAddresses().define(suppressionListAddressId)
    .withExistingSuppressionList(resourceGroupName, emailServiceName, domainResourceName, suppressionListResourceName)
    .withEmail("<email-address-to-suppress>") // Should match the email address you would like to block from receiving your messages
    .create();

You can now try sending an email to the suppressed address from the TryEmail section of your Communication Service resource or by using one of the Email SDKs. Make sure to send the email using the MailFrom address with the sender username you've chosen to suppress. Your email won't send to the suppressed address.

If you try sending an email from a sender username that is not suppressed the email still successfully sends.

Remove an address from a suppression list

Call the delete method on suppressionListAddresses to remove an address from the suppression list.

manager.suppressionListAddresses()
    .delete(resourceGroupName, emailServiceName, domainResourceName, suppressionListResourceName, suppressionListAddressId);

You can now try sending an email to the suppressed address from the TryEmail section of your Communication Service resource or by using one of the Email SDKs. Make sure to send the email using the MailFrom address with the sender username you choose to suppress. Your email will successfully send to the previously suppressed address.

Remove a suppression list from a domain resource

Call the delete method on suppressionLists to remove a suppression list from the domain resource.

manager.suppressionLists()
    .delete(resourceGroupName, emailServiceName, domainResourceName, suppressionListResourceName);

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• An Azure Email Communication Services Resource ready to provision domains. Get started creating an Email Communication Resource.
• An Azure Managed Domain or Custom Domain provisioned and ready to send emails.
• We're using a service principal for authentication. Set the values of the client ID, tenant ID, and client secret of the Azure Active Directory (AD) application as the following environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET.

Install the required packages

pip install azure-mgmt-communication
pip install azure-identity

Initialize the management client

Set the environment variable AZURE_SUBSCRIPTION_ID with the subscription ID of the subscription your Domain and Email resources are in. Run the code sample to initialize the management client.

from azure.mgmt.communication import CommunicationServiceManagementClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
subscription_id = "<your-subscription-id>"

mgmt_client = CommunicationServiceManagementClient(credential, subscription_id)

Add a suppression list to a domain resource

To block your email messages from being sent to certain addresses, the first step is setting up a suppression list in your domain resource.

Update the code sample with the resource group name, the email service name, and the domain resource name for which you would like to create the suppression list. Find this information in the portal by navigating to the domain resource you created when setting up the prerequisites. The title of the resource is <your-email-service-name>/<your-domain-name>. Find the resource group name and subscription ID in the Essentials sections in the domain resource overview. Choose any name for your suppression list resource and update that field in the sample as well.

For the list name, make sure it's the same as the sender username of the MailFrom address you would like to suppress emails from. These MailFrom addresses can be found in the "MailFrom addresses" section of your domain resource in the portal. For example, you may have a MailFrom address that looks like "donotreply@xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.azurecomm.net". The sender username for this address would be "donotreply" so a list name of "donotreply" should be used.

resource_group_name = "<your-resource-group-name>"; # Found in the essentials section of the domain resource portal overview
email_service_name = "<your-email-service-name>"; # Found in the first part of the portal domain resource title
domain_resource_name = "<your-domain-name>"; # Found in the second part of the portal domain resource title
suppression_list_resource_name = "<your-suppression-list-resource-name>";

mgmt_client.suppression_lists.create_or_update(
    resource_group_name,
    email_service_name,
    domain_resource_name,
    suppression_list_resource_name,
    parameters={
        "properties": {
            "listName": "<your-sender-username>" # Should match the sender username of the MailFrom address you would like to suppress emails from
        }
    },
)

If you would like to suppress emails from all the sender usernames in particular domain, you can pass in an empty string for the list name.

mgmt_client.suppression_lists.create_or_update(
    resource_group_name,
    email_service_name,
    domain_resource_name,
    suppression_list_resource_name,
    parameters={
        "properties": {
            "listName": ""
        }
    },
)

Add an address to a suppression list

After setting up the suppression list, you can now add specific email addresses to which you wish to prevent your email messages from being sent.

Update the code sample with the suppression list address ID. Every suppression list address ID you add needs to be unique. We recommend using a GUID. Update the email address you want to block from receiving your messages as well.

To add multiple addresses to the suppression list, you need to repeat this code sample multiple times.

suppression_list_address_id = "<your-suppression-list-address-id>";

mgmt_client.suppression_list_addresses.create_or_update(
    resource_group_name,
    email_service_name,
    domain_resource_name,
    suppression_list_resource_name,
    suppression_list_address_id,
    parameters={
        "properties": {
            "email": "<email-address-to-suppress>" # Should match the email address you would like to block from receiving your messages
        }
    },
)

You can now try sending an email to the suppressed address from the TryEmail section of your Communication Service resource or by using one of the Email SDKs. Make sure to send the email using the MailFrom address with the sender username you choose to suppress. Your email won't send to the suppressed address.

If you try sending an email from a sender username that is not suppressed the email still successfully sends.

Remove an address from a suppression list

Call the delete method on suppression_list_addresses to remove an address from the suppression list.

mgmt_client.suppression_list_addresses.delete(
    resource_group_name,
    email_service_name,
    domain_resource_name,
    suppression_list_resource_name,
    suppression_list_address_id
)

You can now try sending an email to the suppressed address from the TryEmail section of your Communication Service resource or by using one of the Email SDKs. Make sure to send the email using the MailFrom address with the sender username you've chosen to suppress. Your email will successfully send to the previously suppressed address.

Remove a suppression list from a domain resource

Call the delete method on suppression_lists to remove a suppression list from the domain resource.

mgmt_client.suppression_lists.delete(
    resource_group_name,
    email_service_name,
    domain_resource_name,
    suppression_list_resource_name
)