galaxy-game/mail/docs/examples.md

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:

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:

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:

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:

{
  "outcome": "sent"
}

Suppressed response:

{
  "outcome": "suppressed"
}

Async Generic Command Examples

Rendered payload:

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:

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:

curl 'http://127.0.0.1:8080/api/v1/internal/deliveries?source=authsession&status=sent&limit=10'

Get one delivery:

curl http://127.0.0.1:8080/api/v1/internal/deliveries/delivery-123

List attempts:

curl http://127.0.0.1:8080/api/v1/internal/deliveries/delivery-123/attempts

Resend one terminal delivery:

curl -X POST http://127.0.0.1:8080/api/v1/internal/deliveries/delivery-123/resend

Example resend response:

{
  "delivery_id": "delivery-456"
}