adding-azure-communication-services-email

Adding Azure Communication Services Email

Transactional email via Azure Communication Services. Free tier: 100 emails/day, then $0.00025/email. Cheaper than SendGrid for low-volume projects.

When to use ACS Email

Need	Use
Account verification, password reset, transactional notifications	ACS Email (this skill)
Marketing campaigns, newsletters, A/B testing	A marketing-focused provider (Mailchimp, etc.) — ACS doesn't do that
High-volume bulk send (>100k/day)	SendGrid Pro or Mailgun (ACS gets expensive at scale)

The three ACS quirks

1. location: 'global' (literal string, not a real Azure region)

resource emailService 'Microsoft.Communication/emailServices@2023-04-01' = {
  name: emailServiceName
  location: 'global'                  // ← NOT 'australiaeast', NOT location param
  properties: { dataLocation: 'Australia' }
}

If you pass the project's location param (australiaeast), Azure rejects the deploy.

2. dataLocation uses plain English

The values for dataLocation are not Azure region IDs. They're region groupings:

dataLocation value	Where data is stored
'Australia'	AU data centres
'Europe'	EU
'United States'	US
'Asia Pacific'	APAC excluding AU
'Africa'	Africa
'Brazil'	Brazil
'Canada'	Canada
'France'	France
'Germany'	Germany
'India'	India
'Japan'	Japan
'Korea'	Korea
'Norway'	Norway
'Switzerland'	Switzerland
'UAE'	UAE
'United Kingdom'	UK

Use 'Australia' — not 'australiaeast', not 'au', not 'aus'.

3. Declare-order — no dependsOn on email service + domain

ACS resources have an awkward circular dependency: the ACS resource needs to know about the domain, but linkedDomains + dependsOn causes deployment failures.

Declare in this order, with no dependsOn:

// 1. Email service (no dependencies)
resource emailService 'Microsoft.Communication/emailServices@2023-04-01' = {
  name: emailServiceName
  location: 'global'
  properties: { dataLocation: 'Australia' }
}

// 2. Domain — child of emailService
resource emailDomain 'Microsoft.Communication/emailServices/domains@2023-04-01' = {
  parent: emailService
  name: 'AzureManagedDomain'        // or your custom domain
  location: 'global'
  properties: {
    domainManagement: 'AzureManaged'    // or 'CustomerManaged'
    userEngagementTracking: 'Disabled'
  }
}

// 3. Comms service — links to the domain via linkedDomains
resource acs 'Microsoft.Communication/communicationServices@2023-04-01' = {
  name: acsName
  location: 'global'
  properties: {
    dataLocation: 'Australia'
    linkedDomains: [ emailDomain.id ]
  }
}