Add custom email domain to Azure Communication Services (#884)

tjementum · web-flow · commit a4273e4204bd · 2026-05-04T19:25:38.000+02:00
### Summary &amp; Motivation

Switch transactional email sending from the auto-provisioned
`*.azurecomm.net` Azure-managed sender to a brand-aligned
`no-reply@&lt;custom-domain&gt;` sender on Azure Communication Services. The
Azure-managed sender disqualifies the brand from DMARC alignment, sender
reputation tied to the custom domain, and anti-phishing signals such as
Apple Mail's OTP autofill, which requires the sender's eTLD+1 to match
the bound verify-form domain.

- Add an optional `domainName` parameter to
`cloud-infrastructure/modules/communication-services.bicep`. When set,
the module provisions a `CustomerManaged` domain alongside the existing
`AzureManagedDomain`, creates a `no-reply` sender username on it, and
links both domains to the `communicationServices` resource.
- Promote the `CustomerManaged` domain to be the active sender
automatically once its DNS verification status reaches `Verified`. Until
then, the `fromSenderDomain` output stays on the Azure-managed fallback
so transactional email keeps flowing through the verification window.
The existing
`SENDER_EMAIL_ADDRESS=no-reply@${communicationService.outputs.fromSenderDomain}`
wiring on `account-api` and `main-api` picks up the new sender on the
next container app revision, with no env-var or app-code change.
- Pass the cluster's `domainName` parameter (already wired to the
`STAGING_DOMAIN_NAME` and `PRODUCTION_DOMAIN_NAME` GitHub variables and
used today for cluster ingress) into the communication-services module
so the email sender matches the host the user lands on.
- Extend the existing `Show DNS Configuration` step in
`.github/workflows/_deploy-infrastructure.yml` to also surface the ACS
Email custom-domain DNS records. The step uses the same gating pattern
as the cluster-ingress DNS check: silent on first deploy when the
resource does not exist, one line on subsequent runs once the domain is
fully verified, and a list of TXT and CNAME records to add at the
registrar while verification is still pending. While pending, the step
also calls `az communication email domain initiate-verification` for
each record still in `NotStarted`, `VerificationFailed`, or
`CancellationRequested` (idempotent, required because Azure does not
auto-trigger verification when DNS records appear).

### Checklist

- [x] I have added tests, or done manual regression tests
- [x] I have updated the documentation, if necessary
diff --git a/.github/workflows/_deploy-infrastructure.yml b/.github/workflows/_deploy-infrastructure.yml
@@ -87,6 +87,35 @@ jobs:
       - name: Plan Shared Environment Resources
         run: bash ./cloud-infrastructure/environment/deploy-environment.sh ${{ inputs.unique_prefix }} ${{ inputs.azure_environment }} ${{ inputs.shared_location }} ${{ inputs.production_service_principal_object_id }} --plan
 
+      - name: Detect Email Custom Domain Verification
+        if: ${{ inputs.domain_name != '' && inputs.domain_name != '-' }}
+        run: |
+          # Auto-detect whether the email custom domain (eTLD+1 of domain_name) is fully verified in
+          # Azure Communication Services. If yes, export USE_CUSTOM_EMAIL_DOMAIN=true to $GITHUB_ENV
+          # so the next step (Plan Cluster Resources) inherits it; the bicepparam reads the env var
+          # and the Bicep links the CustomerManaged domain + flips SENDER_EMAIL_ADDRESS to no-reply@<apex>.
+          # When not verified (or when the resource does not exist yet on the very first deploy), the
+          # env var stays unset, deploy-cluster.sh defaults it to false, the link is skipped, and mail
+          # keeps flowing on the AzureManaged sender. This means there is no operator toggle to flip:
+          # add DNS, verification completes, the next deploy auto-flips the sender.
+          CLUSTER_RESOURCE_GROUP_NAME="${{ inputs.unique_prefix }}-${{ inputs.azure_environment }}-${{ inputs.cluster_location_acronym }}"
+          email_domain_name=$(echo "${{ inputs.domain_name }}" | awk -F. '{ if (NF >= 2) print $(NF-1)"."$NF; else print $0 }')
+
+          az extension add --name communication --allow-preview true --only-show-errors 2>/dev/null || true
+          email_domain_details=$(az communication email domain show --name "$email_domain_name" --email-service-name $CLUSTER_RESOURCE_GROUP_NAME --resource-group $CLUSTER_RESOURCE_GROUP_NAME -o json 2>/dev/null || echo "")
+
+          if [[ -n "$email_domain_details" ]] && echo "$email_domain_details" | jq empty 2>/dev/null; then
+            domain_status=$(echo "$email_domain_details" | jq -r '.verificationStates.Domain.status // "NotStarted"')
+            spf_status=$(echo "$email_domain_details" | jq -r '.verificationStates.SPF.status // "NotStarted"')
+            dkim_status=$(echo "$email_domain_details" | jq -r '.verificationStates.DKIM.status // "NotStarted"')
+            dkim2_status=$(echo "$email_domain_details" | jq -r '.verificationStates.DKIM2.status // "NotStarted"')
+
+            if [[ "$domain_status" == "Verified" ]] && [[ "$spf_status" == "Verified" ]] && [[ "$dkim_status" == "Verified" ]] && [[ "$dkim2_status" == "Verified" ]]; then
+              echo "USE_CUSTOM_EMAIL_DOMAIN=true" >> $GITHUB_ENV
+              echo "$(date +"%Y-%m-%dT%H:%M:%S") Email custom domain '$email_domain_name' is verified - sender will be no-reply@$email_domain_name."
+            fi
+          fi
+
       - name: Plan Cluster Resources
         id: deploy_cluster
         env:
@@ -142,6 +171,81 @@ jobs:
                 echo "- A CNAME record with the Host name '${{ inputs.back_office_domain_name }}' that points to address 'back-office.$default_domain'."
               fi
             fi
+
+            # Email custom domain DNS. Derived from domain_name as its eTLD+1 (apex) - cluster ingress
+            # is typically a CNAME and DNS forbids TXT/other records at the same name as a CNAME
+            # (RFC 1034); the apex of a domain cannot be a CNAME, so SPF/DKIM records work there. The
+            # awk derivation takes the last two parts of the host (correct for .net, .com, .io; wrong
+            # for multi-part public suffixes like .co.uk - revisit if that ever applies).
+            # Skip silently when the resource does not exist yet, report "configured correctly" once
+            # fully Verified, and only print the records (and kick verification, idempotent) while
+            # there is real work to do. The communication extension is in preview and emits a stderr
+            # banner on every call, so we discard stderr and validate captured stdout is JSON.
+            email_domain_name=$(echo "${{ inputs.domain_name }}" | awk -F. '{ if (NF >= 2) print $(NF-1)"."$NF; else print $0 }')
+            az extension add --name communication --allow-preview true --only-show-errors 2>/dev/null || true
+            email_domain_details=$(az communication email domain show --name "$email_domain_name" --email-service-name $CLUSTER_RESOURCE_GROUP_NAME --resource-group $CLUSTER_RESOURCE_GROUP_NAME -o json 2>/dev/null || echo "")
+
+            if [[ -n "$email_domain_details" ]] && echo "$email_domain_details" | jq empty 2>/dev/null; then
+              domain_status=$(echo "$email_domain_details" | jq -r '.verificationStates.Domain.status // "NotStarted"')
+              spf_status=$(echo "$email_domain_details" | jq -r '.verificationStates.SPF.status // "NotStarted"')
+              dkim_status=$(echo "$email_domain_details" | jq -r '.verificationStates.DKIM.status // "NotStarted"')
+              dkim2_status=$(echo "$email_domain_details" | jq -r '.verificationStates.DKIM2.status // "NotStarted"')
+
+              if [[ "$domain_status" == "Verified" ]] && [[ "$spf_status" == "Verified" ]] && [[ "$dkim_status" == "Verified" ]] && [[ "$dkim2_status" == "Verified" ]]; then
+                echo "$(date +"%Y-%m-%dT%H:%M:%S") Email custom domain '$email_domain_name' is already configured correctly. Sender 'no-reply@$email_domain_name' is active."
+              else
+                # Verification does not auto-start when DNS records appear; kick it on every relevant
+                # type. Idempotent. Domain ownership must be kicked too - without this call, Azure
+                # leaves it in NotStarted forever even after the ms-domain-verification TXT is in DNS.
+                for verification_type in Domain SPF DKIM DKIM2; do
+                  current_status=$(echo "$email_domain_details" | jq -r --arg t "$verification_type" '.verificationStates[$t].status // "NotStarted"')
+                  if [[ "$current_status" == "NotStarted" ]] || [[ "$current_status" == "VerificationFailed" ]] || [[ "$current_status" == "CancellationRequested" ]]; then
+                    az communication email domain initiate-verification --domain-name "$email_domain_name" --email-service-name $CLUSTER_RESOURCE_GROUP_NAME --resource-group $CLUSTER_RESOURCE_GROUP_NAME --verification-type "$verification_type" --only-show-errors 1>/dev/null 2>&1 || true
+                  fi
+                done
+
+                # Red ANSI on the headline so the records jump out in the log; the records themselves
+                # stay plain so they are easy to copy. The final ::error:: directive is a GitHub Actions
+                # workflow command - it surfaces a red annotation in the workflow summary and on any PR
+                # check, not only inline.
+                # Azure returns absolute names for apex records (Domain TXT, SPF TXT) and relative names
+                # for subdomain records (DKIM CNAMEs). DNS UIs (Microsoft 365, Azure DNS, Cloudflare,
+                # Route 53, ...) want "@" as shorthand for the apex - typing the literal full domain
+                # often causes the panel to append the zone again (e.g., "platformplatform.net" becomes
+                # "platformplatform.net.platformplatform.net"). Translate apex hits to "@" so the
+                # operator can paste verbatim into M365's DNS panel.
+                normalize_name() {
+                  if [[ "$1" == "$email_domain_name" ]]; then echo "@"; else echo "$1"; fi
+                }
+
+                echo -e "$(date +"%Y-%m-%dT%H:%M:%S") \033[0;31mPlease add the following DNS entries for the email custom domain and then retry:\033[0m"
+                domain_record_name=$(echo "$email_domain_details" | jq -r '.verificationRecords.Domain.name // ""')
+                domain_record_value=$(echo "$email_domain_details" | jq -r '.verificationRecords.Domain.value // ""')
+                if [[ -n "$domain_record_name" ]]; then echo "- A TXT record with the name '$(normalize_name "$domain_record_name")' (apex of '$email_domain_name') and the value '$domain_record_value' (Domain ownership). This is a separate TXT record - it coexists alongside any existing SPF or other TXT records at the same name."; fi
+                spf_record_name=$(echo "$email_domain_details" | jq -r '.verificationRecords.SPF.name // ""')
+                spf_record_value=$(echo "$email_domain_details" | jq -r '.verificationRecords.SPF.value // ""')
+                if [[ -n "$spf_record_name" ]]; then echo "- A TXT record with the name '$(normalize_name "$spf_record_name")' (apex of '$email_domain_name') and the value '$spf_record_value' (SPF). If a TXT record with this exact value already exists at this name (e.g., from Microsoft 365), no action is needed; if a different SPF value exists, merge the includes so only one SPF record remains."; fi
+                dkim_record_name=$(echo "$email_domain_details" | jq -r '.verificationRecords.DKIM.name // ""')
+                dkim_record_value=$(echo "$email_domain_details" | jq -r '.verificationRecords.DKIM.value // ""')
+                if [[ -n "$dkim_record_name" ]]; then echo "- A CNAME record with the Host name '$dkim_record_name' that points to address '$dkim_record_value' (DKIM selector1)."; fi
+                dkim2_record_name=$(echo "$email_domain_details" | jq -r '.verificationRecords.DKIM2.name // ""')
+                dkim2_record_value=$(echo "$email_domain_details" | jq -r '.verificationRecords.DKIM2.value // ""')
+                if [[ -n "$dkim2_record_name" ]]; then echo "- A CNAME record with the Host name '$dkim2_record_name' that points to address '$dkim2_record_value' (DKIM selector2)."; fi
+
+                # Fail the plan when the email custom domain exists but verification is incomplete.
+                # Letting plan succeed sends the operator into a multi-cycle loop where the apply
+                # eventually links the domain (once verified by a later run) but each interim deploy
+                # silently runs without the desired sender. Surfacing the records and failing now is
+                # cheaper than a 30-minute cycle each iteration.
+                echo "::error::Email custom domain '$email_domain_name' verification is incomplete. Add the DNS records above and re-run this workflow."
+                exit 1
+              fi
+            else
+              # Mirror the cluster-ingress style "checked but no work to confirm" hint so the operator
+              # sees the email check ran. The customer-managed domain only exists after the first apply
+              # with this domain configured; a follow-up workflow run will surface the records.
+              echo "$(date +"%Y-%m-%dT%H:%M:%S") Email custom domain '$email_domain_name' is not yet provisioned in Azure Communication Services. Re-run this workflow after the next apply completes."
+            fi
           else
             echo "$(date +"%Y-%m-%dT%H:%M:%S") DNS configuration instructions will be shown after the Container Apps Environment is created."
           fi
@@ -174,6 +278,31 @@ jobs:
       - name: Deploy Shared Environment Resources
         run: bash ./cloud-infrastructure/environment/deploy-environment.sh ${{ inputs.unique_prefix }} ${{ inputs.azure_environment }} ${{ inputs.shared_location }} ${{ inputs.production_service_principal_object_id }} --apply
 
+      - name: Detect Email Custom Domain Verification
+        if: ${{ inputs.domain_name != '' && inputs.domain_name != '-' }}
+        run: |
+          # Mirror of the plan job's auto-detect step. Re-queries verification because $GITHUB_ENV does
+          # not cross job boundaries; the second az call is cheap. When verified, exports
+          # USE_CUSTOM_EMAIL_DOMAIN=true so the apply links the CustomerManaged domain and the next
+          # account-api/main-api revision picks up the new sender.
+          CLUSTER_RESOURCE_GROUP_NAME="${{ inputs.unique_prefix }}-${{ inputs.azure_environment }}-${{ inputs.cluster_location_acronym }}"
+          email_domain_name=$(echo "${{ inputs.domain_name }}" | awk -F. '{ if (NF >= 2) print $(NF-1)"."$NF; else print $0 }')
+
+          az extension add --name communication --allow-preview true --only-show-errors 2>/dev/null || true
+          email_domain_details=$(az communication email domain show --name "$email_domain_name" --email-service-name $CLUSTER_RESOURCE_GROUP_NAME --resource-group $CLUSTER_RESOURCE_GROUP_NAME -o json 2>/dev/null || echo "")
+
+          if [[ -n "$email_domain_details" ]] && echo "$email_domain_details" | jq empty 2>/dev/null; then
+            domain_status=$(echo "$email_domain_details" | jq -r '.verificationStates.Domain.status // "NotStarted"')
+            spf_status=$(echo "$email_domain_details" | jq -r '.verificationStates.SPF.status // "NotStarted"')
+            dkim_status=$(echo "$email_domain_details" | jq -r '.verificationStates.DKIM.status // "NotStarted"')
+            dkim2_status=$(echo "$email_domain_details" | jq -r '.verificationStates.DKIM2.status // "NotStarted"')
+
+            if [[ "$domain_status" == "Verified" ]] && [[ "$spf_status" == "Verified" ]] && [[ "$dkim_status" == "Verified" ]] && [[ "$dkim2_status" == "Verified" ]]; then
+              echo "USE_CUSTOM_EMAIL_DOMAIN=true" >> $GITHUB_ENV
+              echo "$(date +"%Y-%m-%dT%H:%M:%S") Email custom domain '$email_domain_name' is verified - linking the CustomerManaged domain and flipping the sender."
+            fi
+          fi
+
       - name: Deploy Cluster Resources
         id: deploy_cluster
         env:
diff --git a/cloud-infrastructure/cluster/deploy-cluster.sh b/cloud-infrastructure/cluster/deploy-cluster.sh
@@ -54,6 +54,14 @@ export GOOGLE_OAUTH_CLIENT_SECRET
 export STRIPE_PUBLISHABLE_KEY
 export STRIPE_API_KEY
 export STRIPE_WEBHOOK_SECRET
+# Set to "true" by the deploy workflow's "Detect Email Custom Domain Verification" step once it
+# observes the CustomerManaged email domain (eTLD+1 of DOMAIN_NAME) as fully verified. When true,
+# Bicep links the domain to the CommunicationServices resource and the SENDER_EMAIL_ADDRESS env var
+# on account-api/main-api flips from no-reply@<azurecomm.net> to no-reply@<apex of DOMAIN_NAME>.
+# Defaults to "false" so mail keeps flowing on the AzureManaged sender during the verification window
+# and so the first apply (which always precedes verification) does not fail trying to link an
+# unverified domain. Operators do not flip this manually.
+export USE_CUSTOM_EMAIL_DOMAIN="${USE_CUSTOM_EMAIL_DOMAIN:-false}"
 
 export CONTAINER_REGISTRY_NAME=$UNIQUE_PREFIX$ENVIRONMENT
 export GLOBAL_RESOURCE_GROUP_NAME="$UNIQUE_PREFIX-$ENVIRONMENT-global"
diff --git a/cloud-infrastructure/cluster/main-cluster.bicep b/cloud-infrastructure/cluster/main-cluster.bicep
@@ -15,6 +15,7 @@ param mainVersion string
 param applicationInsightsConnectionString string
 param communicationServicesDataLocation string = 'europe'
 param mailSenderDisplayName string = 'PlatformPlatform'
+param useCustomEmailDomain bool = false
 param revisionSuffix string
 
 @description('Object ID of the Entra ID security group for PostgreSQL administration')
@@ -135,6 +136,20 @@ module stripeSecrets '../modules/key-vault-secrets.bicep' = if (!empty(stripeApi
   }
 }
 
+// Derive the email custom domain as the eTLD+1 (apex) of the cluster's ingress domainName. Cluster
+// ingress is typically a CNAME, and DNS rules forbid TXT/other records at the same name as a CNAME
+// (RFC 1034). The apex of a domain cannot itself be a CNAME, so SPF (TXT) and DKIM CNAMEs at
+// sub-subdomains of the apex can coexist freely with whatever else lives on the apex.
+// Apple Mail OTP autofill matches on eTLD+1, so a sender at the apex still autofills on any subdomain
+// of the same apex (e.g., sender no-reply@platformplatform.net autofills forms on
+// staging.platformplatform.net or app.platformplatform.net).
+// The "last two parts" derivation is correct for single-suffix TLDs (.net, .com, .io). It is wrong
+// for multi-part public suffixes like .co.uk - replace with an explicit param if that ever applies.
+var domainNameParts = split(domainName, '.')
+var emailDomainName = empty(domainName)
+  ? ''
+  : '${domainNameParts[length(domainNameParts) - 2]}.${domainNameParts[length(domainNameParts) - 1]}'
+
 module communicationService '../modules/communication-services.bicep' = {
   scope: clusterResourceGroup
   name: '${clusterResourceGroupName}-communication-services'
@@ -144,6 +159,8 @@ module communicationService '../modules/communication-services.bicep' = {
     dataLocation: communicationServicesDataLocation
     mailSenderDisplayName: mailSenderDisplayName
     keyVaultName: keyVault.outputs.name
+    emailDomainName: emailDomainName
+    useCustomEmailDomain: useCustomEmailDomain
   }
 }
 
diff --git a/cloud-infrastructure/cluster/main-cluster.bicepparam b/cloud-infrastructure/cluster/main-cluster.bicepparam
@@ -7,6 +7,7 @@ param globalResourceGroupName = readEnvironmentVariable('GLOBAL_RESOURCE_GROUP_N
 param environment = readEnvironmentVariable('ENVIRONMENT')
 param containerRegistryName = readEnvironmentVariable('CONTAINER_REGISTRY_NAME')
 param domainName = readEnvironmentVariable('DOMAIN_NAME', '')
+param useCustomEmailDomain = readEnvironmentVariable('USE_CUSTOM_EMAIL_DOMAIN', 'false') == 'true'
 param backOfficeDomainName = readEnvironmentVariable('BACK_OFFICE_DOMAIN_NAME', '')
 param backOfficeEntraClientId = readEnvironmentVariable('BACK_OFFICE_ENTRA_CLIENT_ID')
 param backOfficeAdminsGroupId = readEnvironmentVariable('BACK_OFFICE_ADMINS_GROUP_ID', '')
diff --git a/cloud-infrastructure/modules/communication-services.bicep b/cloud-infrastructure/modules/communication-services.bicep
