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
Open the Azure portal to create a new resource.
Search for Email Communication Services.
Select Email Communication Services and press Create
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.
Click Next: Review + create.
Wait for the validation to pass, then click Create.
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:
- Login into your Azure account
- Select Subscriptions in the left sidebar
- Select whichever subscription is needed
- Click on Overview
- 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 = "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e";
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 = "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e";
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 = "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e";
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 = "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e";
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 = "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e";
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
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