Email Service Provisioning¶

This page walks through provisioning an Azure Communication Services (ACS) Email channel end to end, with screenshots from a real deployment. It covers the order in which resources must be created, the difference between Azure Managed Domains and custom verified domains, and the linkage required between the Email Communication Service and the ACS resource that ultimately sends mail.

For a generic ACS resource walk-through (without email), see Provisioning ACS Resources.

Prerequisites¶

• An Azure subscription with the Microsoft.Communication resource provider registered.
• An existing or planned ACS resource (will be linked to the Email Communication Service).
• For custom domains: control of the DNS zone (ability to add TXT records).
• Azure CLI 2.50+ with the communication extension, or Portal access.

When to Use¶

Procedure¶

Step 1. Create the Email Communication Service¶

The Email Communication Service is a distinct Azure resource from the ACS resource. It owns the verified domains; the ACS resource owns the connection string that the SDK uses. They are linked in a later step.

az communication email create \
  --name "ecs-email-lab" \
  --location "Global" \
  --data-location "Korea" \
  --resource-group "rg-acs-email-lab"

After creation, the Email Service Overview blade renders with the Essentials section populated and two call-to-action cards prompting domain setup:

Step 2. Provision domains (managed vs. custom)¶

Open the Provision domains blade from the Email Service left navigation. This is the grid where every domain associated with the service appears, regardless of whether it is Azure-managed or a custom verified domain.

The grid contrasts the two domain types you can attach:

To add an AzureManagedDomain via CLI:

az communication email domain create \
  --domain-name "AzureManagedDomain" \
  --email-service-name "ecs-email-lab" \
  --resource-group "rg-acs-email-lab" \
  --location "Global" \
  --domain-management AzureManaged

To add a custom domain (verification follows in step 3):

az communication email domain create \
  --domain-name "contoso-demo.example.com" \
  --email-service-name "ecs-email-lab" \
  --resource-group "rg-acs-email-lab" \
  --location "Global" \
  --domain-management CustomerManaged

Step 3. Verify a custom domain via DNS¶

When you click Configure on any of the four status columns (Domain, SPF, DKIM, DKIM2) for a custom domain, the Portal opens a separate wizard per record. The capture below shows the first wizard (Domain TXT), which is the gating record that proves you own the domain.

The four wizards must complete in order: Domain TXT first (proves ownership), then SPF (sender policy), then DKIM and DKIM2 (signing keys). Each wizard polls the DNS resolver after you click Done — propagation typically completes within minutes but can take up to 30 minutes depending on your DNS provider and TTL.

After all four records verify, the Provision domains grid (step 2) will show all four columns as Verified for the custom domain.

Step 4. Link the domain to the ACS resource¶

The Email Communication Service owns the domain; the ACS resource owns the connection string the SDK uses. Until you connect them, calling EmailClient.send with the ACS connection string returns a permission error.

Open the ACS resource → Email → Domains blade and use Connect domain:

CLI equivalent:

az communication update \
  --name "acs-email-lab" \
  --resource-group "rg-acs-email-lab" \
  --linked-domains "/subscriptions/<subscription-id>/resourceGroups/rg-acs-email-lab/providers/Microsoft.Communication/emailServices/ecs-email-lab/domains/AzureManagedDomain"

The --linked-domains flag is additive: pass every domain you want the ACS resource to be allowed to send from. Removing a domain from this list immediately revokes the ACS resource's ability to send from it.

Step 5. Configure sender usernames (MailFrom)¶

Each linked domain exposes a MailFrom addresses blade where you can manage the local-part of sender addresses (the bit before the @).

CLI equivalent for a custom domain:

az communication email domain sender-username create \
  --domain-name "contoso-demo.example.com" \
  --email-service-name "ecs-email-lab" \
  --resource-group "rg-acs-email-lab" \
  --sender-username "support" \
  --display-name "Contoso Support"

Verification¶

After completing all five steps, verify the deployment by sending one email through the SDK:

# Confirm the domain is linked
az communication show \
  --name "acs-email-lab" \
  --resource-group "rg-acs-email-lab" \
  --query "linkedDomains" -o tsv

# Confirm the domain is verified
az communication email domain show \
  --domain-name "AzureManagedDomain" \
  --email-service-name "ecs-email-lab" \
  --resource-group "rg-acs-email-lab" \
  --query "verificationStates" -o json

Then send a test email using one of the SDK tutorials:

• Python — Send Email
• JavaScript — Send Email
• Java — Send Email
• .NET — Send Email

A successful send returns a message ID with status: "Succeeded". The mail typically reaches the recipient inbox within 3–6 seconds for AzureManagedDomain → Gmail/Outlook routes (measured during this guide's capture session).

Rollback / Troubleshooting¶

For deeper troubleshooting (delivery failures, bounce analysis, DMARC interaction) see:

• Email Delivery Failures Playbook
• Domain Verification Playbook
• Email Delivery Checklist (First 10 Minutes)

See Also¶

• Provisioning ACS Resources — generic ACS resource creation (without email)
• Monitoring Azure Communication Services — diagnostic settings + Log Analytics for the resources created here
• Send Email Tutorial (Python)
• Email with Attachments Recipe (Python)

Sources¶

• Quickstart: Create an Email Communication Service resource
• Quickstart: How to add Azure Managed Domains to Email Communication Service
• Quickstart: How to add custom verified domains to Email Communication Service
• Quickstart: How to connect a verified email domain