docs(email): add email backend document

Author: sudip-khanal

utils/email/docs/email.md

@@ -0,0 +1,111 @@
+## Overview
+This system supports **pluggable email backends** in Django, allowing dynamic switching between:
+
+- SMTP-based email delivery (default Django backend)
+- Custom HTTP API-based email delivery
+
+## Backend Selection
+- The email backend is controlled via environment variables:
+- **SMTP Backend (Development)**
+    ```env
+    EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
+    EMAIL_HOST=mailpit
+    EMAIL_PORT=1025
+    EMAIL_USE_TLS=False
+    ````
+- **Custom API Backend (Production)**
+    ```env
+    EMAIL_BACKEND=utils.email.CustomEmailBackend
+    EMAIL_API_ENDPOINT=<API_ENDPOINT>
+    EMAIL_API_KEY=<API_KEY>
+    EMAIL_API_TIMEOUT=30
+    ```
+
+
+## High-Level Architecture
+```mermaid
+flowchart TD
+    A["Django App<br/>(send_mail / EmailMessage)"]
+    B["EMAIL_BACKEND<br/>(Configured via ENV)"]
+    C["SMTP Backend"]
+    D["Custom Email Backend"]
+    A --> B
+    B --> C
+    B --> D
+```
+
+## Custom Email Backend Components
+
+- Base Email Backend (`EmailBackend`)
+    - An abstract class extending Django’s `BaseEmailBackend`, responsible for handling HTTP-based email delivery.
+    - Manage HTTP session lifecycle (`open`, `close`)
+    - Ensure thread safety using `threading.RLock`
+    - Send email messages via HTTP POST
+    - Handle API responses (success/failure)
+    - Provide reusable utilities (e.g., Base64 encoding)
+
+- Custom Email Backend (`CustomEmailBackend`)
+     - Implementation of `EmailBackend` for a specific external email API.
+    - Transform `EmailMessage` into API-compatible payload
+    - Encode email fields using Base64
+    - Support HTML and plain text email content
+
+**Key Methods**
+
+| Method              | Description                            |
+| ------------------- | -------------------------------------- |
+| `open()`            | Initializes HTTP session               |
+| `close()`           | Closes HTTP session                    |
+| `send_messages()`   | Sends batch of email messages          |
+| `_send_message()`   | Sends a single email                   |
+| `_build_headers()`  | Constructs HTTP headers                |
+| `_build_payload()`  | Abstract method for payload generation |
+| `_handle_success()` | Handles successful response            |
+| `_handle_failure()` | Handles failed response                |
+
+## Request Flow
+1. Django constructs an `EmailMessage`
+2. `send_messages()` is invoked by the backend
+3. A thread-safe session is initialized
+4. For each message:
+   - `_build_headers()` prepares HTTP headers
+   - `_build_payload()` converts message to API format
+   - HTTP POST request is sent to the API endpoint
+5. Response handling:
+   - Success → logged and counted
+   - Failure → logged and optionally raises exception
+
+## Header Construction
+Default headers
+```http
+Content-Type: application/json
+X-API-KEY: <API_KEY>
+```
+> Note: `X-API-KEY` is currently used for authentication. This can be extended in the future to support other authentication schemes.
+
+
+## Payload Format
+The email message is converted into a JSON payload:
+
+```json
+{
+  "FromAsBase64": "<encoded>",
+  "ToAsBase64": "<encoded>",
+  "CcAsBase64": "<encoded>",
+  "BccAsBase64": "<encoded>",
+  "SubjectAsBase64": "<encoded>",
+  "BodyAsBase64": "<encoded>",
+  "IsBodyHtml": true
+}
+```
+
+### Details
+- All fields are Base64-encoded
+- HTML content is preferred if available
+- Falls back to plain text body otherwise
+
+
+## Thread Safety
+- A `threading.RLock` is used to ensure safe concurrent access
+- Prevents race conditions when multiple threads send emails
+- Ensures session reuse without corruption