feat: mail service

mail/docs/examples.md

@@ -0,0 +1,129 @@
+# Configuration and Contract Examples
+
+The examples below are illustrative. IDs, timestamps, and keys are placeholders
+unless explicitly stated otherwise.
+
+## Example Environment
+
+Minimal local runtime with stub provider:
+
+```dotenv
+MAIL_REDIS_ADDR=127.0.0.1:6379
+MAIL_INTERNAL_HTTP_ADDR=:8080
+MAIL_TEMPLATE_DIR=templates
+MAIL_SMTP_MODE=stub
+
+OTEL_TRACES_EXPORTER=none
+OTEL_METRICS_EXPORTER=none
+```
+
+SMTP-backed shape:
+
+```dotenv
+MAIL_REDIS_ADDR=127.0.0.1:6379
+MAIL_INTERNAL_HTTP_ADDR=:8080
+MAIL_TEMPLATE_DIR=templates
+
+MAIL_SMTP_MODE=smtp
+MAIL_SMTP_ADDR=127.0.0.1:1025
+MAIL_SMTP_FROM_EMAIL=noreply@example.com
+MAIL_SMTP_TIMEOUT=15s
+# Optional for local self-signed SMTP capture only:
+# MAIL_SMTP_INSECURE_SKIP_VERIFY=true
+
+OTEL_TRACES_EXPORTER=none
+OTEL_METRICS_EXPORTER=none
+```
+
+## Auth Delivery REST
+
+Request:
+
+```bash
+curl -X POST http://127.0.0.1:8080/api/v1/internal/login-code-deliveries \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: challenge-123' \
+  -d '{
+    "email": "pilot@example.com",
+    "code": "123456",
+    "locale": "fr-FR"
+  }'
+```
+
+Success response:
+
+```json
+{
+  "outcome": "sent"
+}
+```
+
+Suppressed response:
+
+```json
+{
+  "outcome": "suppressed"
+}
+```
+
+## Async Generic Command Examples
+
+Rendered payload:
+
+```bash
+redis-cli XADD mail:delivery_commands '*' \
+  delivery_id mail-123 \
+  source notification \
+  payload_mode rendered \
+  idempotency_key notification:mail-123 \
+  request_id req-123 \
+  trace_id trace-123 \
+  payload_json '{"to":["pilot@example.com"],"cc":[],"bcc":[],"reply_to":[],"subject":"Turn ready","text_body":"Turn 54 is ready.","html_body":"<p>Turn <strong>54</strong> is ready.</p>","attachments":[]}'
+```
+
+Template payload:
+
+```bash
+redis-cli XADD mail:delivery_commands '*' \
+  delivery_id mail-124 \
+  source notification \
+  payload_mode template \
+  idempotency_key notification:mail-124 \
+  request_id req-124 \
+  trace_id trace-124 \
+  payload_json '{"to":["pilot@example.com"],"cc":[],"bcc":[],"reply_to":[],"template_id":"game.turn_ready","locale":"fr-FR","variables":{"turn_number":54},"attachments":[]}'
+```
+
+## Operator API Examples
+
+List deliveries:
+
+```bash
+curl 'http://127.0.0.1:8080/api/v1/internal/deliveries?source=authsession&status=sent&limit=10'
+```
+
+Get one delivery:
+
+```bash
+curl http://127.0.0.1:8080/api/v1/internal/deliveries/delivery-123
+```
+
+List attempts:
+
+```bash
+curl http://127.0.0.1:8080/api/v1/internal/deliveries/delivery-123/attempts
+```
+
+Resend one terminal delivery:
+
+```bash
+curl -X POST http://127.0.0.1:8080/api/v1/internal/deliveries/delivery-123/resend
+```
+
+Example resend response:
+
+```json
+{
+  "delivery_id": "delivery-456"
+}
+```