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:sendaccepts the full ACS payload (senderAddress,contentwithsubject/plainText/html,recipientsto/cc/bcc,attachments,replyTo,headers) and returns202 AcceptedwithOperation-LocationandRetry-Afterheaders for polling. A caller-suppliedOperation-Idrequest 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 isSucceeded - Inspection mailbox:
GET /emailMessageslists every captured message,GET /emailMessages/{operationId}returns one in full (including the original request body), andDELETE /emailMessagesclears the mailbox - ARM management plane:
Microsoft.Communication/communicationServices,.../emailServices, and.../emailServices/{name}/domains/{domain}CreateOrUpdate, Get, Delete, and List, pluscheckNameAvailabilityfor 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
| 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
emailstorage backend, so they followfloci-az.storage.services.email.mode(the globalstorage.modeby default,memoryunless set). - Operations always succeed immediately. There is no
Running→Succeededtransition delay and no failure simulation.Retry-After: 3is still returned on the202to match ACS, but the first poll already reportsSucceeded. - Auth is permissive. The connection-string access key and
Authorizationheader are accepted but not validated (dev mode), matching the rest of the emulator. - ARM resources are state-only.
communicationServices/emailServices/domainsreturnSucceededprovisioning 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 answers409 Conflict, and the name is free again once the owner deletes it.checkNameAvailabilityanswers from the same owners, in any subscription, with the reasons and messages of the spec examples (AlreadyExists,NameAvailable), and answersInvalidfor a name outside the communication service name rule (1 to 63 letters, digits, underscores and hyphens); a body whosetypenames 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.