{
  "openapi": "3.0.3",
  "info": {
    "title": "tempy.email Developer API",
    "description": "Create disposable email addresses programmatically. No sign-up or authentication required.\n\nTwo interfaces available:\n- **Simple API** (content negotiation at root URLs) — requires `Accept: application/json` header\n- **Full API** (versioned prefix at /api/v1) — standard REST endpoints",
    "version": "1.0.0",
    "contact": {
      "name": "tempy.email",
      "url": "https://tempy.email/developers"
    }
  },
  "servers": [
    {
      "url": "https://tempy.email",
      "description": "Simple API (content negotiation)"
    },
    {
      "url": "https://tempy.email/api/v1",
      "description": "Full API (versioned prefix)"
    }
  ],
  "paths": {
    "/": {
      "post": {
        "operationId": "createMailboxSimple",
        "summary": "Create mailbox (simple API)",
        "description": "Creates a disposable mailbox. Requires `Accept: application/json` header. Same functionality as POST /api/v1/mailbox.",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "enum": ["application/json"] }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateMailboxRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mailbox created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreateMailboxResponse" }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/{address}": {
      "get": {
        "operationId": "getMessagesSimple",
        "summary": "Get messages (simple API)",
        "description": "Returns messages for a mailbox. Requires `Accept: application/json` header. Add `?threads` query parameter to group messages by subject.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "brave.pixel.a1b2c@tempy.email"
          },
          {
            "name": "Accept",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "enum": ["application/json"] }
          },
          {
            "name": "threads",
            "in": "query",
            "required": false,
            "schema": { "type": "boolean" },
            "description": "If present, group messages into threads by subject"
          }
        ],
        "responses": {
          "200": {
            "description": "Messages (flat array or threaded)",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/MessagesResponse" },
                    { "$ref": "#/components/schemas/ThreadsResponse" }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Mailbox not found or expired",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/mailbox": {
      "post": {
        "operationId": "createMailbox",
        "summary": "Create a new disposable mailbox",
        "description": "Creates a disposable email address with a 10-minute lifetime. The returned email address serves as both the inbox and the API key for subsequent requests. Optionally configure a webhook to receive incoming emails in real time.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMailboxRequest"
              },
              "examples": {
                "simple": {
                  "summary": "Basic mailbox (no webhook)",
                  "value": {}
                },
                "withWebhook": {
                  "summary": "Mailbox with JSON webhook",
                  "value": {
                    "webhook_url": "https://your-server.com/webhook",
                    "webhook_format": "json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mailbox created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateMailboxResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (bad webhook URL or format)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/mailbox/{address}": {
      "get": {
        "operationId": "getMailbox",
        "summary": "Check mailbox status",
        "description": "Returns the current status and remaining lifetime of a mailbox.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "example": "brave.pixel.a1b2c@tempy.email"
          }
        ],
        "responses": {
          "200": {
            "description": "Mailbox status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MailboxStatusResponse"
                }
              }
            }
          },
          "404": {
            "description": "Mailbox not found or expired",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteMailbox",
        "summary": "Deactivate mailbox",
        "description": "Immediately deactivates the mailbox. No new emails will be accepted.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Mailbox deactivated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Mailbox not found or already expired",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/mailbox/{address}/messages": {
      "get": {
        "operationId": "getMessages",
        "summary": "List messages in a mailbox",
        "description": "Returns all emails received by and sent from this mailbox.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of messages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessagesResponse"
                }
              }
            }
          },
          "404": {
            "description": "Mailbox not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateMailboxRequest": {
        "type": "object",
        "properties": {
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to receive incoming emails via HTTP POST",
            "example": "https://your-server.com/webhook"
          },
          "webhook_format": {
            "type": "string",
            "enum": ["json", "xml"],
            "default": "json",
            "description": "Format of the webhook payload"
          }
        }
      },
      "CreateMailboxResponse": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "The disposable email address",
            "example": "brave.pixel.a1b2c@tempy.email"
          },
          "web_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to view this mailbox in the web UI",
            "example": "https://tempy.email/?mailbox=brave.pixel.a1b2c"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the mailbox expires"
          },
          "seconds_remaining": {
            "type": "integer",
            "description": "Seconds until expiration",
            "example": 600
          },
          "webhook_url": {
            "type": "string",
            "nullable": true,
            "description": "Configured webhook URL, if any"
          },
          "webhook_format": {
            "type": "string",
            "description": "Webhook payload format",
            "example": "json"
          }
        }
      },
      "MailboxStatusResponse": {
        "type": "object",
        "properties": {
          "email": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "expires_at": { "type": "string", "format": "date-time" },
          "seconds_remaining": { "type": "integer" },
          "is_expired": { "type": "boolean" }
        }
      },
      "MessagesResponse": {
        "type": "object",
        "properties": {
          "email": { "type": "string" },
          "count": { "type": "integer" },
          "messages": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Message" }
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "from": { "type": "string" },
          "to": { "type": "string" },
          "subject": { "type": "string" },
          "body_text": { "type": "string" },
          "received_at": { "type": "string", "format": "date-time" },
          "message_id": { "type": "string", "nullable": true },
          "direction": {
            "type": "string",
            "enum": ["inbound", "outbound"]
          },
          "is_read": { "type": "boolean" }
        }
      },
      "ThreadsResponse": {
        "type": "object",
        "properties": {
          "email": { "type": "string" },
          "thread_count": { "type": "integer" },
          "threads": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "subject": { "type": "string" },
                "message_count": { "type": "integer" },
                "latest_at": { "type": "string", "format": "date-time" },
                "messages": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Message" }
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message"
          }
        }
      },
      "WebhookPayload": {
        "type": "object",
        "description": "Payload sent to your webhook URL when an email arrives",
        "properties": {
          "id": { "type": "string" },
          "from": { "type": "string" },
          "to": { "type": "string" },
          "subject": { "type": "string" },
          "body_text": { "type": "string" },
          "received_at": { "type": "string", "format": "date-time" },
          "message_id": { "type": "string", "nullable": true },
          "direction": { "type": "string", "enum": ["inbound"] }
        }
      }
    }
  }
}