Skip to content

Azure Communication Services: Email

Compatible with the azure-communication-email SDK, the Microsoft.Communication ARM management plane, and any HTTP client. Floci AZ emulates the ACS Email data plane (POST /emails:send plus status polling) and captures every message in-memory for local inspection: a Mailpit-style mailbox for your tests. No real email is ever delivered.

HTTP-only: no Docker. Sending, status polling, inspection, and ARM resources are all in-process. There is no sidecar.


Features

  • Send email: POST /emails:send accepts the full ACS payload (senderAddress, content with subject/plainText/html, recipients to/cc/bcc, attachments, replyTo, headers) and returns 202 Accepted with Operation-Location and Retry-After headers for polling. A caller-supplied Operation-Id request header is adopted as the operation id; without one the emulator generates a UUID, matching ACS
  • Operation status: GET /emails/operations/{operationId} reports the long-running operation status as {"id":…,"status":…,"error":null}, the same shape ACS returns. The emulator completes immediately, so the status is Succeeded
  • Inspection mailbox: GET /emailMessages lists every captured message, GET /emailMessages/{operationId} returns one in full (including the original request body), and DELETE /emailMessages clears the mailbox
  • ARM management plane: Microsoft.Communication/communicationServices, .../emailServices, and .../emailServices/{name}/domains/{domain} CreateOrUpdate, Get, Delete, and List, plus checkNameAvailability for communication service names

Endpoints

POST   /emails:send                              # data-plane send → 202 + Operation-Location
GET    /emails/operations/{operationId}          # operation status (Succeeded)

GET    /emailMessages                            # list captured messages
GET    /emailMessages/{operationId}              # single captured message detail
DELETE /emailMessages                            # clear the mailbox

PUT/GET/DELETE .../providers/Microsoft.Communication/communicationServices/{name}
PUT/GET/DELETE .../providers/Microsoft.Communication/emailServices/{name}
PUT/GET/DELETE .../providers/Microsoft.Communication/emailServices/{name}/domains/{domain}
POST   /subscriptions/{sub}/providers/Microsoft.Communication/checkNameAvailability

The send and polling paths are also served when the SDK targets the ACS host form https://{resource}.communication.azure.com (use FLOCI_AZ_HOSTNAME/your hosts file to point that name at the emulator), or via the path-style /{account}-email/ suffix.


Quickstart

Send an email (Python SDK)

from azure.communication.email import EmailClient

# In dev mode the access key is not validated
client = EmailClient.from_connection_string(
    "endpoint=http://localhost:4577/;accesskey=<any-base64-key>")

poller = client.begin_send({
    "senderAddress": "DoNotReply@example.com",
    "content": {"subject": "Hello", "plainText": "Hi from floci-az!"},
    "recipients": {"to": [{"address": "dev@example.com"}]},
})
result = poller.result()
print(result["id"], result["status"])   # operationId, Succeeded

Send with curl

curl -s -X POST "http://localhost:4577/emails:send?api-version=2023-03-31" \
  -H "Content-Type: application/json" \
  -d '{
    "senderAddress": "DoNotReply@example.com",
    "content": {"subject": "Hello", "plainText": "Hi!"},
    "recipients": {"to": [{"address": "dev@example.com"}]}
  }'
# → 202 Accepted, Operation-Location: .../emails/operations/{operationId}

Inspect the captured mailbox

# List everything that was "sent"
curl -s "http://localhost:4577/emailMessages"
# → {"value":[{"operationId":"...","status":"Succeeded","subject":"Hello","toCount":1, ...}], "count":1}

# Fetch one message in full (includes the original request body)
curl -s "http://localhost:4577/emailMessages/<operationId>"

# Clear the mailbox between tests
curl -s -X DELETE "http://localhost:4577/emailMessages"

This makes it easy to assert in tests that your code sent the right subject, recipients, and body, without an SMTP server or a real ACS resource.


Configuration

floci-az:
  services:
    email:
      enabled: true
Env var Default Description
FLOCI_AZ_SERVICES_EMAIL_ENABLED true Enable/disable the service

Notes & limitations

  • No delivery. Messages are captured, never sent: nothing goes out over SMTP and no external recipient receives anything. The mailbox and the ARM resources are kept in the email storage backend, so they follow floci-az.storage.services.email.mode (the global storage.mode by default, memory unless set).
  • Operations always succeed immediately. There is no Running→Succeeded transition delay and no failure simulation. Retry-After: 3 is still returned on the 202 to match ACS, but the first poll already reports Succeeded.
  • Auth is permissive. The connection-string access key and Authorization header are accepted but not validated (dev mode), matching the rest of the emulator.
  • ARM resources are state-only. communicationServices/emailServices/domains return Succeeded provisioning state with synthesized properties (hostName, dataLocation); domain verification (SPF/DKIM TXT records) is not emulated.
  • Communication service names are global. A communication service owns {name}.communication.azure.com: the first subscription to create a name owns it, a create of the same name from another subscription or resource group answers 409 Conflict, and the name is free again once the owner deletes it. checkNameAvailability answers from the same owners, in any subscription, with the reasons and messages of the spec examples (AlreadyExists, NameAvailable), and answers Invalid for a name outside the communication service name rule (1 to 63 letters, digits, underscores and hyphens); a body whose type names another resource type is always available. Email services and domains are scoped to their resource group. A path that differs from the creating one only in case addresses the same resource, which keeps the casing of its first PUT.