{
  "name": "mail",
  "title": "Ravencraft Mail Service",
  "version": "0.1.0",
  "base_url": "https://services.ravencraft.dk/mail",
  "description": "Send transactional emails via a simple JSON API (API-key protected). Uses SMTP (tls/ssl) configured in services.mail.smtp.",
  "auth": {
    "type": "api_key",
    "in": "header",
    "header": "X-API-Key"
  },
  "endpoints": [
    {
      "method": "POST",
      "path": "/send",
      "returns": "application/json",
      "summary": "Send an email.",
      "body": {
        "to": { "type": "string", "format": "email", "required": true },
        "from": {
          "type": "string",
          "format": "email",
          "required": false,
          "note": "If omitted, uses services.mail.smtp.from_email"
        },
        "reply_to": { "type": "string", "format": "email", "required": false },
        "subject": { "type": "string", "required": true, "max": 180 },
        "text": { "type": "string", "required": false, "max_bytes": 200000 },
        "html": { "type": "string", "required": false, "max_bytes": 200000 },
        "request_id": { "type": "string", "required": false },
        "tenant_id": { "type": "string", "required": false },
        "user_id": { "type": "string", "required": false }
      },
      "responses": {
        "200": { "status": "OK", "request_id": "string", "message_id": "string" },
        "400": { "status": "ERROR", "code": "string", "message": "string" },
        "401": { "status": "DOWN", "message": "Unauthorized" },
        "413": { "status": "ERROR", "code": "body_too_large", "message": "string" },
        "429": { "status": "ERROR", "code": "rate_limited", "message": "string" },
        "500": { "status": "ERROR", "code": "send_failed", "message": "string" }
      }
    },
    {
      "method": "GET",
      "path": "/health.php",
      "returns": "application/json",
      "summary": "Health check."
    },
    {
      "method": "GET",
      "path": "/help.php",
      "returns": "text/html",
      "summary": "Human documentation."
    }
  ],
  "logging": {
    "via": "/shared/log_client.php",
    "events": ["mail.request", "mail.sent", "mail.error", "mail.help.view"]
  },
  "limits": {
    "max_body_bytes_per_field": 200000
  }
}