Edit

Share via

Quickstart: How to add Azure Managed Domains to Email Communication Service

  • Article

This article describes how to provision an Azure Managed Domain for Email Communication Service in Azure Communication Services.

Prerequisites

Provision Azure Managed Domain

  1. Open the Overview page of the Email Communications Service resource that you created in Get started with Creating Email Communication Resource.

  2. Create an Azure Managed Domain using one of the following options.

    • (Option 1) Click the 1-click add button under Add a free Azure subdomain. Continue to step 3.

    Screenshot that highlights the adding a free Azure Managed Domain.

    • (Option 2) Click Provision Domains on the left navigation panel.

    Screenshot that shows the Provision Domains navigation page.

    • Click Add domain on the upper navigation bar.
    • Select Azure domain from the dropdown.

  3. Wait for the deployment to complete.

    Screenshot that shows the Deployment Progress.

  4. Once the domain is created, you see a list view with the new domain.

    Screenshot that shows the list of provisioned email domains.

  5. Click the name of the provisioned domain to open the overview page for the domain resource type.

    Screenshot that shows Azure Managed Domain overview page.

Prerequisites

Create Domain resource

To create a Domain resource, sign in to Azure CLI. You can sign in running the az login command from the terminal and providing your credentials. To create the resource, run the following command:

az communication email domain create --domain-name AzureManagedDomain --email-service-name "<EmailServiceName>" --location "Global" --resource-group "<resourceGroup>" --domain-management AzureManaged

If you would like to select a specific subscription, you can also specify the --subscription flag and provide the subscription ID.

az communication email domain create --domain-name AzureManagedDomain --email-service-name "<EmailServiceName>" --location "Global" --resource-group "<resourceGroup>" --domain-management AzureManaged --subscription "<subscriptionId>"

You can configure your Domain resource with the following options:

  • The resource group
  • The name of the Email Communication Services resource
  • The geography the resource will be associated with
  • The name of the Domain resource:
    • For Azure domains, the name should be AzureManagedDomain.
  • The value of the Domain management property.
    • For Azure domains, the value should be AzureManaged.

In the next step, you can assign tags to the domain resource. Tags can be used to organize your Domain resources. For more information about tags, see the resource tagging documentation.

Manage your Domain resource

To add tags to your Domain resource, run the following commands. You can target a specific subscription as well.

az communication email domain update --domain-name AzureManagedDomain --email-service-name "<EmailServiceName>" --resource-group "<resourceGroup>" --tags newTag="newVal1"

az communication email domain update --domain-name AzureManagedDomain --email-service-name "<EmailServiceName>" --resource-group "<resourceGroup>" --tags newTag="newVal1" --subscription "<subscriptionId>"

To list all of your Domain Resources in a given Email Communication Service, use the following command:

az communication email domain list --email-service-name "<EmailServiceName>" --resource-group "<resourceGroup>"

To show all the information on a given domain resource use the following command:

az communication email domain show --domain-name AzureManagedDomain --email-service-name "<EmailServiceName>" --resource-group "<resourceGroup>"

Clean up Domain resource

If you want to clean up and remove a Domain resource, You can delete by running the following command.

az communication email domain delete --domain-name AzureManagedDomain --email-service-name "<EmailServiceName>" --resource-group "<resourceGroup>"

Note

Resource deletion is permanent and no data, including event grid filters, phone numbers, or other data tied to your resource, can be recovered if you delete the resource.

For information on other commands, see Domain CLI.

Prerequisites

Installing the SDK

First, include the Communication Services Management SDK in your C# project:

using Azure.ResourceManager.Communication;

Subscription ID

You need to know the ID of your Azure subscription. This can be acquired from the portal:

  1. Login into your Azure account
  2. Select Subscriptions in the left sidebar
  3. Select whichever subscription is needed
  4. Click on Overview
  5. Select your Subscription ID

In this quickstart, we'll assume that you've stored the subscription ID in an environment variable called AZURE_SUBSCRIPTION_ID.

Authentication

To communicate with Domain resource, you must first authenticate yourself to Azure.

Authenticate the Client

The default option to create an authenticated client is to use DefaultAzureCredential. Since all management APIs go through the same endpoint, in order to interact with resources, only one top-level ArmClient has to be created.

To authenticate to Azure and create an ArmClient, do the following code:

using System;
using System.Threading.Tasks;
using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Communication;
using Azure.ResourceManager.Resources;
...
// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

Interacting with Azure resources

Now that you're authenticated.

For each of the following examples, we'll be assigning our Domain resources to an existing Email communication service.

If you need to create an Email Communication Service, you can do so by using the Azure portal.

Create a Domain resource

When creating a Domain resource, you have to specify the resource group name, Email Communication Service name, resource name and DomainManagement.

Note

The Location property is always global.

// this example assumes you already have this EmailServiceResource created on azure
// for more information of creating EmailServiceResource, please refer to the document of EmailServiceResource
string subscriptionId = "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e";
string resourceGroupName = "MyResourceGroup";
string emailServiceName = "MyEmailServiceResource";
ResourceIdentifier emailServiceResourceId = EmailServiceResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, emailServiceName);
EmailServiceResource emailServiceResource = client.GetEmailServiceResource(emailServiceResourceId);

// get the collection of this CommunicationDomainResource
CommunicationDomainResourceCollection collection = emailServiceResource.GetCommunicationDomainResources();

// invoke the operation
string domainName = "AzureManagedDomain";
CommunicationDomainResourceData data = new CommunicationDomainResourceData(new AzureLocation("Global"))
{
    DomainManagement = DomainManagement.AzureManaged,
};
ArmOperation<CommunicationDomainResource> lro = await collection.CreateOrUpdateAsync(WaitUntil.Completed, domainName, data);            
CommunicationDomainResource result = lro.Value;

// the variable result is a resource, you could call other operations on this instance as well
// but just for demo, we get its data from this resource instance
CommunicationDomainResourceData resourceData = result.Data;
// for demo we just print out the id
Console.WriteLine($"Succeeded on id: {resourceData.Id}");

Manage your Domain Resources

Update a Domain resource

...
// this example assumes you already have this CommunicationDomainResource created on azure
// for more information of creating CommunicationDomainResource, please refer to the document of CommunicationDomainResource
string subscriptionId = "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e";
string resourceGroupName = "MyResourceGroup";
string emailServiceName = "MyEmailServiceResource";
string domainName = "AzureManagedDomain";
ResourceIdentifier communicationDomainResourceId = CommunicationDomainResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, emailServiceName, domainName);
CommunicationDomainResource communicationDomainResource = client.GetCommunicationDomainResource(communicationDomainResourceId);

// invoke the operation
CommunicationDomainResourcePatch patch = new CommunicationDomainResourcePatch()
{
    Tags =
    {
    ["newTag"] = "newVal",
    },
};
ArmOperation<CommunicationDomainResource> lro = await communicationDomainResource.UpdateAsync(WaitUntil.Completed, patch);
CommunicationDomainResource result = lro.Value;

// the variable result is a resource, you could call other operations on this instance as well
// but just for demo, we get its data from this resource instance
CommunicationDomainResourceData resourceData = result.Data;
// for demo we just print out the id
Console.WriteLine($"Succeeded on id: {resourceData.Id}");

List by Email Service

// this example assumes you already have this EmailServiceResource created on azure
// for more information of creating EmailServiceResource, please refer to the document of EmailServiceResource
string subscriptionId = "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e";
string resourceGroupName = "MyResourceGroup";
string emailServiceName = "MyEmailServiceResource";
ResourceIdentifier emailServiceResourceId = EmailServiceResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, emailServiceName);
EmailServiceResource emailServiceResource = client.GetEmailServiceResource(emailServiceResourceId);

// get the collection of this CommunicationDomainResource
CommunicationDomainResourceCollection collection = emailServiceResource.GetCommunicationDomainResources();

// invoke the operation and iterate over the result
await foreach (CommunicationDomainResource item in collection.GetAllAsync())
{
    // the variable item is a resource, you could call other operations on this instance as well
    // but just for demo, we get its data from this resource instance
    CommunicationDomainResourceData resourceData = item.Data;
    // for demo we just print out the id
    Console.WriteLine($"Succeeded on id: {resourceData.Id}");
}

Console.WriteLine($"Succeeded");

Get Domain resource

// this example assumes you already have this EmailServiceResource created on azure
// for more information of creating EmailServiceResource, please refer to the document of EmailServiceResource
string subscriptionId = "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e";
string resourceGroupName = "MyResourceGroup";
string emailServiceName = "MyEmailServiceResource";
ResourceIdentifier emailServiceResourceId = EmailServiceResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, emailServiceName);
EmailServiceResource emailServiceResource = client.GetEmailServiceResource(emailServiceResourceId);

// get the collection of this CommunicationDomainResource
CommunicationDomainResourceCollection collection = emailServiceResource.GetCommunicationDomainResources();

// invoke the operation
string domainName = "AzureManagedDomain";
bool result = await collection.ExistsAsync(domainName);

Console.WriteLine($"Succeeded: {result}");

Clean up a Domain resource

// this example assumes you already have this CommunicationDomainResource created on azure
// for more information of creating CommunicationDomainResource, please refer to the document of CommunicationDomainResource
string subscriptionId = "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e";
string resourceGroupName = "MyResourceGroup";
string emailServiceName = "MyEmailServiceResource";
string domainName = "AzureManagedDomain";
ResourceIdentifier communicationDomainResourceId = CommunicationDomainResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, emailServiceName, domainName);
CommunicationDomainResource communicationDomainResource = client.GetCommunicationDomainResource(communicationDomainResourceId);

// invoke the operation
await communicationDomainResource.DeleteAsync(WaitUntil.Completed);

Console.WriteLine($"Succeeded");

Note

Resource deletion is permanent and no data, including event grid filters, phone numbers, or other data tied to your resource, can be recovered if you delete the resource.

Prerequisites

Create a Domain resource

To create a Domain resource, Sign into your Azure account by using the Connect-AzAccount using the following command and provide your credentials.

PS C:\> Connect-AzAccount

First, make sure to install the Azure Communication Services module Az.Communication using the following command.

PS C:\> Install-Module Az.Communication

Run the following command to create the Azure managed domain resource:

PS C:\> New-AzEmailServiceDomain -ResourceGroupName ContosoResourceProvider1 -EmailServiceName ContosoEmailServiceResource1 -Name AzureManagedDomain -DomainManagement AzureManaged

You can configure your Domain resource with the following options:

  • The resource group
  • The name of the Email Communication Services resource.
  • The name of the Domain resource:
    • For Azure domains, the name should be - AzureManagedDomain.
  • The value of the Domain management property.
    • For Azure domains, the value should be AzureManaged.

In the next step, you can assign tags to the domain resource. Tags can be used to organize your Domain resources. For more information about tags, see the resource tagging documentation.

Manage your Domain resource

To add tags to your Domain resource, run the following commands. You can target a specific subscription as well.

PS C:\> Update-AzEmailServiceDomain -Name AzureManagedDomain -EmailServiceName ContosoEmailServiceResource1 -ResourceGroupName ContosoResourceProvider1 -Tag @{ExampleKey1="ExampleValue1"}

PS C:\> Update-AzEmailServiceDomain -Name AzureManagedDomain -EmailServiceName ContosoEmailServiceResource1 -ResourceGroupName ContosoResourceProvider1 -Tag @{ExampleKey1="ExampleValue1"} -SubscriptionId SubscriptionID

To list all of your Domain Resources in a given Email Communication Service, use the following command:

PS C:\> Get-AzEmailServiceDomain -EmailServiceName ContosoEmailServiceResource1 -ResourceGroupName ContosoResourceProvider1

To list all the information on a given domain resource, use the following command:

PS C:\> Get-AzEmailServiceDomain -Name AzureManagedDomain -EmailServiceName ContosoEmailServiceResource1 -ResourceGroupName ContosoResourceProvider1

Clean up a Domain resource

If you want to clean up and remove a Domain resource, You can delete your Domain resource by running the following command:

PS C:\> Remove-AzEmailServiceDomain -Name AzureManagedDomain -EmailServiceName ContosoEmailServiceResource1 -ResourceGroupName ContosoResourceProvider1

Note

Resource deletion is permanent and no data, including event grid filters, phone numbers, or other data tied to your resource, can be recovered if you delete the resource.

Azure Managed Domains compared to Custom Domains

Before provisioning an Azure Managed Domain, review the following table to decide which domain type best meets your needs.

Azure Managed Domains Custom Domains
Pros: - Setup is quick & easy
- No domain verification required
 - Emails are sent from your own domain
Cons: - Sender domain is not personalized and cannot be changed
- Sender usernames can't be personalized
- Very limited sending volume
- User Engagement Tracking can't be enabled
- Requires verification of domain records
- Longer setup for verification

Service limits

Both Azure managed domains and Custom domains are subject to service limits. Service limits include failure, rate, and size limits. For more information, see Service limits for Azure Communication Services > Email.

Sender authentication for Azure Managed Domain

Azure Communication Services automatically configures the required email authentication protocols for the email as described in Email Authentication best practices.

Your email domain is now ready to send emails.

Next steps