Email with Azure Communication Services

Derived from Create and manage Email Communication Service resources, Quickstart: Create and manage Communication Services resources, and Azure CLI reference — az communication email.

[[Domain verification]] == Domain verification

An Azure-managed domain needs no verification step — it is created already verified. A custom domain moves through three verification passes, each triggered with az communication email domain initiate-verification --verification-type <type> (Domain, SPF, DKIM, DKIM2, DMARC) after the matching DNS record is in place; DNS propagation typically takes 15-30 minutes before a verification attempt succeeds.

Derived from Add custom verified email domains and Azure CLI reference — az communication email domain.

az communication email send is a synchronous convenience command that submits the message and polls az communication email status get internally until the message reaches a final state:

A connection string is the only way the communication CLI extension itself authenticates — there is no az login-based option for these two commands — so treat $CONNECTION_STRING the way any other credential on this site is treated: read it from Key Vault (Key Vault and Secrets) for a real pipeline, never hard-code it in a script or commit it to source control. Application code has the better option below.

Derived from Send an email using Azure Communication Services and Azure CLI reference — az communication email.

The Email SDK authenticates with DefaultAzureCredential against the Communication Services resource’s endpoint, exactly like every other Bookshelf service on this site (Identity and Access) — notifier’s managed identity needs no stored connection string at all, only a role assignment (`Contributor or the narrower built-in Communication and Email Service Owner role) scoped to cs-bookshelf:

beginSend returns a long-running-operation poller rather than blocking synchronously, so notifier (running as a Container Apps job, per Container Apps: Scaling, Jobs and Dapr) can fire the send and either wait on the poller inline for a short job or check status on a later invocation via emailClient.getSendStatus(operationId). The .NET and Python Email SDKs expose the same EmailClient/DefaultAzureCredential shape and are the better starting point than Java only when the rest of the calling service is already .NET or Python (Bookshelf’s own services are Spring Boot, so Java is the default here).

Derived from Azure Communication Email client library for Java and Send an email using Azure Communication Services.

[[SMTP relay]] == SMTP relay

Where a library or platform only speaks SMTP — an existing JavaMailSender bean, a legacy on-call alerting tool, a CMS plugin — Azure Communication Services also exposes an authenticated SMTP relay at smtp.azurecomm.net:587, STARTTLS, rather than requiring every caller to adopt the Email SDK. Authentication is still Microsoft Entra ID, not a shared SMTP password: a Microsoft Entra application is registered, granted the Communication and Email Service Owner role (or Contributor) on cs-bookshelf, and its client secret becomes the SMTP password. The SMTP username is not the app’s client ID alone — it is the three-part string <communication-services-resource-name>.<entra-app-id>.<entra-tenant-id> (e.g. cs-bookshelf.11111111-1111-1111-1111-111111111111.22222222-2222-2222-2222-222222222222), which is how the relay knows which Communication Services resource and which Entra tenant to authenticate the connection against.

With spring-boot-starter-mail on the classpath, this configuration is all Spring Boot needs to autowire a JavaMailSender — no code change from the plain-SMTP MailSender/JavaMailSender setup already shown on Configuration and Profiles, just a different host/username shape and ${ACS_SMTP_PASSWORD} sourced from Key Vault rather than committed to a properties file. The Quarkus Mailer extension configures the same relay through quarkus.mailer.* properties exactly as Scheduling and Mail describes for any other SMTP provider, pointed at smtp.azurecomm.net:587 with start-tls=REQUIRED and this same three-part username.

Derived from Authenticate to the Azure Communication Services SMTP relay.

[[Delivery status and engagement tracking]] == Delivery status and engagement tracking via Event Grid

Rather than polling az communication email status get or the SDK’s getSendStatus, Azure Communication Services publishes delivery outcomes — and, on a domain with User Engagement Tracking enabled, opens and link clicks — directly to Event Grid:

Subscribing `notifier’s own status handler this way lets Bookshelf record a bounce against the customer’s order without adding a poll loop anywhere in the request path.

Derived from Azure Communication Services — Email events and Handle Email events.

[[Quotas and limits]] == Quotas and limits

Every subscription starts with conservative send rate limits and grows them only on request, since Azure Communication Services shares outbound IP reputation across every tenant using the service:

Azure-managed domains cannot request a higher limit at all; a verified custom domain can, and Azure Communication Services documents supporting up to 1-2 million messages per hour for accounts that earn it. A handful of other size/resource limits apply regardless of domain type: at most 50 recipients across to/cc/bcc per message (more needs a support request), a 10 MB cap on the total request size including attachments (roughly 7.5 MB of actual attachment content once Base64’s ~33% overhead is accounted for; larger files are better sent as a Blob Storage link with a SAS, per Blob Storage), at most 100 sender usernames per domain, and at most 100 domains linked to one Communication Services resource.

Requesting a quota increase is a standard Azure support request (Service and Subscription Limits (Quotas) as the issue type), evaluated on sender reputation rather than granted automatically: Microsoft looks at the domain’s failure rate (bounces, complaints, blocks), and asks for it to stay under 1% before approving a higher limit — requests typically take up to 72 hours, and Microsoft’s own guidance is to ramp volume up gradually over two to four weeks on a new domain rather than starting at, or requesting, a high limit on day one, so that third-party mail providers have time to build trust in the domain’s new sending IPs.

Derived from Service limits for Azure Communication Services — Email and Quota increase for email domains.

[[The outbound port 25 block]] == The outbound port 25 block

Azure blocks outbound TCP port 25 from most compute services — virtual machines, VM Scale Sets, App Service, Container Apps, AKS nodes — on most subscription types, to protect the shared IP reputation of Azure’s own address space from being used for unauthenticated spam relaying; there is no per-resource opt-out, and the block applies independent of any NSG rule the caller configures on their own subnet. This is precisely why Azure Communication Services (both the Email SDK and the SMTP relay above) and third-party relays such as SendGrid exist as the recommended path: they listen on port 587 with mandatory authenticated SMTP (STARTTLS plus a credential, never anonymous relay), which Azure does not block on any subscription type, and they additionally carry their own established sending reputation rather than an ordinary VM’s arbitrary outbound IP. An application or script that tries to talk directly to a recipient’s port 25 mail server from an Azure compute resource — rather than through an authenticated relay like ACS or SendGrid — fails outright rather than degrading, which is the most common report behind "email works locally but not from our VM."

Derived from Troubleshoot outbound SMTP connectivity in Azure.