# jitesh-raut/azure-email-communication-service-for-sending-emails architecture

> Architecture diagram of the GitHub repository jitesh-raut/azure-email-communication-service-for-sending-emails, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jitesh-raut/azure-email-communication-service-for-sending-emails
- Repository: https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails

## Overview

#### Purpose and Entry Points
This is a small Python sample repository for sending email through Azure Communication Services (ACS). It demonstrates two independent execution paths:
- ACS Email SDK client: `SendEmail_ACS_EmailClient.py`
- Standard SMTP submission: `SendEmail_ACS_SMTP.py`

`README.md` is the operational guide for provisioning Azure resources, linking a verified domain, and configuring credentials.

#### Azure Resource and Domain Boundary
Before either sender can work, Azure infrastructure must exist: an Email Communication Service, an Azure Communication Service resource, and a verified/managed email domain connected to ACS. The sender address must belong to that connected domain.

The repository does not provision infrastructure programmatically; these are manual Azure Portal steps documented in `README.md`.

#### SDK-Based Email Send Path
`SendEmail_ACS_EmailClient.py` uses the Azure Communication Email Python SDK and connection-string authentication. Its primary flow is:
1. Create `EmailClient` from an ACS connection string.
2. Construct an email payload with sender, recipients, subject, and plaintext content.
3. Call the asynchronous `begin_send` operation.
4. Block on the returned poller for the send result.

This path crosses directly from the local Python runtime to the ACS Email API, with authentication bounded by the ACS connection string.

#### SMTP-Based Email Send Path
`SendEmail_ACS_SMTP.py` uses Python’s SMTP/email libraries to submit a MIME message. Its control flow is:
1. Build a multipart MIME email and populate headers/body.
2. Open an SMTP connection to ACS.
3. Upgrade the connection with STARTTLS.
4. Authenticate and submit the serialized message.
5. Close the SMTP session.

The remote SMTP boundary is `smtp.azurecomm.net` on port 587, with TLS 1.2+ required.

#### Identity and Authorization for SMTP
SMTP authentication uses Microsoft Entra application credentials rather than an ACS connection string. The SMTP username combines ACS resource name, Entra application ID, and tenant ID; the password is an Entra client secret.

The Entra service principal needs ACS permissions equivalent to Communication Services read and Email Services write. Role assignment and credential lifecycle are external Azure/Entra operational concerns described in `README.md`.

#### Data Flow and Operational Constraints
Both paths accept equivalent logical data: verified sender address, recipient address(es), subject, and message content. They differ only at the delivery transport/authentication boundary:
- SDK payload and ACS connection string: `SendEmail_ACS_EmailClient.py`
- MIME serialization, SMTP/STARTTLS, and Entra credentials: `SendEmail_ACS_SMTP.py`

Scripts are intended for local Python execution and use placeholder values that must be replaced before use. The SDK route requires the `azure-communication-email` package; SMTP relies on Python standard-library modules.

Main entry points: [`README.md`](https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/README.md) (Operational guide), [`SendEmail_ACS_EmailClient.py`](https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_EmailClient.py) (Send poller), [`SendEmail_ACS_SMTP.py`](https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_SMTP.py) (SMTP sender)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local Python"]
  node_sdk_script["SDK sender<br/>Python script"]
  node_sdk_client["EmailClient<br/>SDK client"]
  node_sdk_payload["Email payload<br/>message model"]
  node_send_poller["Send poller<br/>async operation"]
  node_smtp_script["SMTP sender<br/>Python script"]
  node_mime_message["MIME message<br/>serialized email"]
end

subgraph group_azure["Azure Communication Services"]
  node_domain["Verified email domain<br/>Azure domain"]
  node_acs_resource{{"ACS resource<br/>Azure resource"}}
  node_email_service{{"Email Communication Service<br/>Azure resource"}}
  node_smtp_submission["ACS SMTP endpoint<br/>SMTP service"]
  node_acs_roles["ACS role assignments<br/>authorization"]
end

subgraph group_identity["Microsoft Entra ID"]
  node_service_principal["SMTP service principal<br/>Entra application"]
  node_client_secret["Client secret<br/>Entra credential"]
end

node_guide["Operational guide<br/>documentation<br/>[README.md]"]

node_guide -.->|"documents provisioning"| node_email_service
node_guide -.->|"documents provisioning"| node_acs_resource
node_guide -.->|"documents linkage"| node_domain
node_domain -->|"connected to"| node_acs_resource
node_sdk_script -->|"creates"| node_sdk_client
node_sdk_script -->|"builds"| node_sdk_payload
node_sdk_client -->|"begin_send"| node_send_poller
node_sdk_payload -->|"submitted as"| node_send_poller
node_send_poller -->|"ACS Email API"| node_email_service
node_smtp_script -->|"builds"| node_mime_message
node_mime_message -->|"submits over STARTTLS"| node_smtp_submission
node_smtp_script -->|"opens and closes session"| node_smtp_submission
node_service_principal -->|"uses"| node_client_secret
node_service_principal -->|"SMTP username identity"| node_smtp_submission
node_client_secret -->|"SMTP password"| node_smtp_submission
node_acs_roles -->|"granted to"| node_service_principal
node_smtp_submission -->|"delivers through"| node_email_service
node_email_service -->|"uses sender domain"| node_domain

click node_guide "https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/README.md"
click node_sdk_script "https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_EmailClient.py"
click node_sdk_client "https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_EmailClient.py"
click node_sdk_payload "https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_EmailClient.py"
click node_send_poller "https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_EmailClient.py"
click node_smtp_script "https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_SMTP.py"
click node_mime_message "https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_SMTP.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk_script,node_sdk_client,node_sdk_payload,node_send_poller,node_smtp_script,node_mime_message toneBlue
class node_domain,node_acs_resource,node_email_service,node_smtp_submission,node_acs_roles toneAmber
class node_service_principal,node_client_secret toneMint
class node_guide toneNeutral
```

## Components

### Local Python

- [SDK sender](https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_EmailClient.py): Python script · `SendEmail_ACS_EmailClient.py`
- [EmailClient](https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_EmailClient.py): SDK client · Created with an ACS connection string. · `SendEmail_ACS_EmailClient.py`
- [Email payload](https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_EmailClient.py): message model · Sender, recipients, subject, and plaintext body. · `SendEmail_ACS_EmailClient.py`
- [Send poller](https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_EmailClient.py): async operation · Waits for the ACS send result. · `SendEmail_ACS_EmailClient.py`
- [SMTP sender](https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_SMTP.py): Python script · `SendEmail_ACS_SMTP.py`
- [MIME message](https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/SendEmail_ACS_SMTP.py): serialized email · Multipart message with headers and body. · `SendEmail_ACS_SMTP.py`

### Azure Communication Services

- **Verified email domain**: Azure domain · Sender addresses must belong to this ACS-connected domain.
- **ACS resource**: Azure resource
- **Email Communication Service**: Azure resource
- **ACS SMTP endpoint**: SMTP service · smtp.azurecomm.net:587 with STARTTLS (TLS 1.2+).
- **ACS role assignments**: authorization · Requires Communication Services read and Email Services write permissions.

### Microsoft Entra ID

- **SMTP service principal**: Entra application · Application ID and tenant ID form part of the SMTP username.
- **Client secret**: Entra credential · Used as the SMTP password.

### Other components

- [Operational guide](https://github.com/jitesh-raut/azure-email-communication-service-for-sending-emails/blob/main/README.md): documentation · Manual provisioning, domain linkage, roles, and credentials. · `README.md`

## Connections

- Operational guide → Email Communication Service: documents provisioning
- Operational guide → ACS resource: documents provisioning
- Operational guide → Verified email domain: documents linkage
- Verified email domain → ACS resource: connected to
- SDK sender → EmailClient: creates
- SDK sender → Email payload: builds
- EmailClient → Send poller: begin_send
- Email payload → Send poller: submitted as
- Send poller → Email Communication Service: ACS Email API
- SMTP sender → MIME message: builds
- MIME message → ACS SMTP endpoint: submits over STARTTLS
- SMTP sender → ACS SMTP endpoint: opens and closes session
- SMTP service principal → Client secret: uses
- SMTP service principal → ACS SMTP endpoint: SMTP username identity
- Client secret → ACS SMTP endpoint: SMTP password
- ACS role assignments → SMTP service principal: granted to
- ACS SMTP endpoint → Email Communication Service: delivers through
- Email Communication Service → Verified email domain: uses sender domain