Quickstart: Create and manage Email Communication Service resources

Get started with Email by provisioning your first Email Communication Service resource. Provision Email Communication Service resources through the Azure portal or using the .NET management client library. The management client library and the Azure portal enable you to create, configure, update, and delete your resources and interface using Azure's deployment and management service: Azure Resource Manager. All functions available in the client libraries are available in the Azure portal.

Warning

Note that it is not possible to create a resource group at the same time as a resource for Azure Communication Services. When creating a resource, a resource group that has been created already must be used.

Prerequisites

• An Azure account with an active subscription. Create an account for free.

Create the Email Communications Service resource using portal

1. Open the Azure portal to create a new resource.

2. Search for Email Communication Services.

   

3. Select Email Communication Services and press Create

   

4. Enter the required information in the Basics tab:

   • Select an existing Azure subscription.

   • Select an existing resource group, or create a new one by clicking the Create new link.

   • Provide a valid name for the resource.

   • Select the region where the resource needs to be available.

   • Select United States as the data location.

   • To add tags, click Next: Tags

   • Add any name/value pairs.

     

5. Click Next: Review + create.

6. Wait for the validation to pass, then click Create.

7. Wait for the Deployment to complete, then click Go to Resource to open the Email Communication Service overview.

   

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• Install Azure CLI

Create Email Communication Services resource

To create an Email Communication Services 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 create --name "<EmailServiceName>" --location "Global" --data-location "United States" --resource-group "<resourceGroup>"

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

az communication email create --name "<EmailServiceName>" --location "Global" --data-location "United States" --resource-group "<resourceGroup>" --subscription "<subscriptionId>"

You can configure your Email Communication Services resource with the following options:

• The resource group
• The name of the Email Communication Services resource
• The geography the resource will be associated with

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

Manage your Email Communication Services resource

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

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

az communication email update --name "<EmailServiceName>" --tags newTag="newVal2" --resource-group "<resourceGroup>" --subscription "<subscriptionId>"

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

az communication email list --resource-group "<resourceGroup>"

To show all the information on a given Email Communication Service resource use the following command. You can target a specific subscription as well.

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

az communication email show --name "<EmailServiceName>" --resource-group "<resourceGroup>" --subscription "<subscriptionId>"

Clean up resource

If you want to clean up and remove an Email Communication Services subscription, you can delete the resource or resource group. You can delete your email communication resource by running the following command.

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

Deleting the resource group also deletes any other resources associated with it.

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 Email Communication CLI.

Prerequisites

• An Azure account with an active subscription. Create an account for free.
• The latest version .NET Core SDK for your operating system.
• Get the latest version of the .NET Identity SDK.
• Get the latest version of the .NET Management SDK.

Installing the SDK

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

using Azure.ResourceManager.Communication;

Subscription ID

You'll 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 Azure Communication Services, 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 Email Services resources to an existing resource group.

If you need to create a resource group, you can do so by using the Azure portal or the Azure Resource Manager SDK.

Create an Email Services resource

When creating an Email Services resource, you'll specify the resource group name and resource name.

Note

The Location property is always global, and during public preview the DataLocation value must be UnitedStates.

// this example assumes you already have this ResourceGroupResource created on azure
// for more information of creating ResourceGroupResource, please refer to the document of ResourceGroupResource
string subscriptionId = "11112222-3333-4444-5555-666677778888";
string resourceGroupName = "MyResourceGroup";
ResourceIdentifier resourceGroupResourceId = ResourceGroupResource.CreateResourceIdentifier(subscriptionId, resourceGroupName);
ResourceGroupResource resourceGroupResource = client.GetResourceGroupResource(resourceGroupResourceId);

// get the collection of this EmailServiceResource
EmailServiceResourceCollection collection = resourceGroupResource.GetEmailServiceResources();

// invoke the operation
string emailServiceName = "MyEmailServiceResource";
EmailServiceResourceData data = new EmailServiceResourceData(new AzureLocation("Global"))
{
    DataLocation = "United States",
};
ArmOperation<EmailServiceResource> lro = await collection.CreateOrUpdateAsync(WaitUntil.Completed, emailServiceName, data);
EmailServiceResource 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
EmailServiceResourceData resourceData = result.Data;
// for demo we just print out the id
Console.WriteLine($"Succeeded on id: {resourceData.Id}");

Manage your Email Communication Services resource

Update an Email Communication Services 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 = "11112222-3333-4444-5555-666677778888";
string resourceGroupName = "MyResourceGroup";
string emailServiceName = "MyEmailServiceResource";
ResourceIdentifier emailServiceResourceId = EmailServiceResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, emailServiceName);
EmailServiceResource emailServiceResource = client.GetEmailServiceResource(emailServiceResourceId);

// invoke the operation
EmailServiceResourcePatch patch = new EmailServiceResourcePatch()
{
    Tags =
    {
    ["newTag"] = "newVal",
    },
};
ArmOperation<EmailServiceResource> lro = await emailServiceResource.UpdateAsync(WaitUntil.Completed, patch);
EmailServiceResource 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
EmailServiceResourceData resourceData = result.Data;
// for demo we just print out the id
Console.WriteLine($"Succeeded on id: {resourceData.Id}");

List all Email Communication Service resources by resource group

// this example assumes you already have this ResourceGroupResource created on azure
// for more information of creating ResourceGroupResource, please refer to the document of ResourceGroupResource
string subscriptionId = "11112222-3333-4444-5555-666677778888";
string resourceGroupName = "MyResourceGroup";
ResourceIdentifier resourceGroupResourceId = ResourceGroupResource.CreateResourceIdentifier(subscriptionId, resourceGroupName);
ResourceGroupResource resourceGroupResource = client.GetResourceGroupResource(resourceGroupResourceId);

// get the collection of this EmailServiceResource
EmailServiceResourceCollection collection = resourceGroupResource.GetEmailServiceResources();

// invoke the operation and iterate over the result
await foreach (EmailServiceResource 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
    EmailServiceResourceData resourceData = item.Data;
    // for demo we just print out the id
    Console.WriteLine($"Succeeded on id: {resourceData.Id}");
}

Console.WriteLine($"Succeeded");

List all Email Communication Service resources by subscription

// this example assumes you already have this SubscriptionResource created on azure
// for more information of creating SubscriptionResource, please refer to the document of SubscriptionResource
string subscriptionId = "11112222-3333-4444-5555-666677778888";
ResourceIdentifier subscriptionResourceId = SubscriptionResource.CreateResourceIdentifier(subscriptionId);
SubscriptionResource subscriptionResource = client.GetSubscriptionResource(subscriptionResourceId);

// invoke the operation and iterate over the result
await foreach (EmailServiceResource item in subscriptionResource.GetEmailServiceResourcesAsync())
{
    // 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
    EmailServiceResourceData resourceData = item.Data;
    // for demo we just print out the id
    Console.WriteLine($"Succeeded on id: {resourceData.Id}");
}

Console.WriteLine($"Succeeded");

Clean up 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 = "11112222-3333-4444-5555-666677778888";
string resourceGroupName = "MyResourceGroup";
string emailServiceName = "MyEmailServiceResource";
ResourceIdentifier emailServiceResourceId = EmailServiceResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, emailServiceName);
EmailServiceResource emailServiceResource = client.GetEmailServiceResource(emailServiceResourceId);

// invoke the operation
await emailServiceResource.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

• An Azure account with an active subscription. Create an account for free.
• Install the Azure Az PowerShell Module

Create Email Communication Service resource

To create an Email Communication Service 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

To create the resource, run the following command:

PS C:\> New-AzEmailService -ResourceGroupName ContosoResourceProvider1 -Name ContosoEmailServiceResource1 -DataLocation UnitedStates

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

PS C:\> New-AzEmailService -ResourceGroupName ContosoResourceProvider1 -Name ContosoEmailServiceResource1 -DataLocation UnitedStates -SubscriptionId SubscriptionID

You can configure your Communication Services resource with the following options:

• The resource group
• The name of the Email Communication Services resource
• The geography the resource will be associated with

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

Manage your Email Communication Services resource

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

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

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

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

PS C:\> Get-AzEmailService -SubscriptionId SubscriptionID

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

PS C:\> Get-AzEmailService -Name ContosoEmailServiceResource1 -ResourceGroupName ContosoResourceProvider1

Clean up resource

If you want to clean up and remove an Email Communication Services, You can delete your Email communication resource by running the following command:

PS C:\> Remove-AzEmailService -Name 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.

Next steps

• Email domains and sender authentication for Azure Communication Services

• Quickstart: How to connect a verified email domain

Related articles

• Familiarize yourself with the Email client library
• Learn how to send emails with custom verified domains in Quickstart: How to add custom verified email domains
• Learn how to send emails with Azure Managed Domains in Quickstart: How to add Azure Managed Domains to email