# 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"
}
```