{
  "openapi": "3.1.0",
  "info": {
    "title": "tkic Mail API",
    "version": "1.0.0",
    "description": "Public API to create temporary @tkic.gg addresses and read incoming mail. Built for Discord bots, websites, and scripts.",
    "contact": {
      "url": "https://discord.gg/tkic"
    }
  },
  "servers": [{ "url": "https://tkic.gg" }],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Service health",
        "operationId": "health",
        "responses": {
          "200": {
            "description": "Service is up",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "domain": { "type": "string", "example": "tkic.gg" },
                    "docs": { "type": "string", "format": "uri" },
                    "openapi": { "type": "string", "format": "uri" },
                    "rate_limit": {
                      "type": "object",
                      "properties": {
                        "create_inbox_per_minute": { "type": "integer", "example": 20 }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/inbox": {
      "post": {
        "summary": "Create a temporary inbox",
        "description": "Limit: 20 creations per minute per IP (X-RateLimit-* headers).",
        "operationId": "createInbox",
        "responses": {
          "200": {
            "description": "Inbox created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InboxCreated" }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RateLimitError" }
              }
            }
          }
        }
      }
    },
    "/api/inbox/{token}": {
      "get": {
        "summary": "Infos sur une boîte",
        "operationId": "getInbox",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Boîte trouvée",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InboxInfo" }
              }
            }
          },
          "404": { "description": "Token inconnu" }
        }
      }
    },
    "/api/inbox/{token}/messages": {
      "get": {
        "summary": "Lister les messages",
        "operationId": "listMessages",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Liste des messages (sans corps complet)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "messages": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/MessageSummary" }
                    }
                  }
                }
              }
            }
          },
          "404": { "description": "Token inconnu" }
        }
      }
    },
    "/api/inbox/{token}/messages/{messageId}": {
      "get": {
        "summary": "Lire un message",
        "operationId": "getMessage",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Message complet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "$ref": "#/components/schemas/MessageFull" }
                  }
                }
              }
            }
          },
          "404": { "description": "Token ou message inconnu" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "InboxCreated": {
        "type": "object",
        "required": ["token", "address", "created_at"],
        "properties": {
          "token": { "type": "string", "format": "uuid" },
          "address": { "type": "string", "example": "abc123xyz0@tkic.gg" },
          "created_at": { "type": "integer", "description": "Unix ms" }
        }
      },
      "InboxInfo": {
        "type": "object",
        "properties": {
          "address": { "type": "string" },
          "created_at": { "type": "integer" }
        }
      },
      "MessageSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "from_addr": { "type": "string" },
          "from_name": { "type": "string", "nullable": true },
          "subject": { "type": "string" },
          "received_at": { "type": "integer" }
        }
      },
      "MessageFull": {
        "allOf": [
          { "$ref": "#/components/schemas/MessageSummary" },
          {
            "type": "object",
            "properties": {
              "text_body": { "type": "string", "nullable": true },
              "html_body": { "type": "string", "nullable": true }
            }
          }
        ]
      },
      "RateLimitError": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "enum": ["rate_limit"] },
          "message": { "type": "string" },
          "retry_after": { "type": "integer" }
        }
      }
    }
  }
}