{
  "openapi": "3.0.4",
  "info": {
    "title": "TempHotmail Mailbox API",
    "version": "1.0.0",
    "description": "Create Premium mailboxes and read incoming mail with an active Pro subscription. Account keys access all Premium mailboxes in the account. AI & CLI keys access only the mailboxes they created."
  },
  "servers": [
    {
      "url": "https://temphotmail.com/api/v1"
    }
  ],
  "security": [
    {
      "BearerKey": []
    }
  ],
  "paths": {
    "/mailboxes": {
      "post": {
        "operationId": "createMailbox",
        "summary": "Create a Premium mailbox",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._-]{1,128}$"
            },
            "required": false,
            "description": "Replay the original successful result for 24 hours with the same key and parameters."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Optional local part. Defaults to a random name."
                  },
                  "domain": {
                    "type": "string",
                    "description": "Optional allowed Premium domain. Defaults to the first configured Premium domain."
                  }
                }
              },
              "example": {}
            }
          }
        },
        "responses": {
          "201": {
            "description": "Mailbox created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Mailbox"
                    }
                  }
                }
              }
            }
          },
          "200": {
            "description": "Original creation result replayed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Mailbox"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "413": {
            "$ref": "#/components/responses/Error413"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      },
      "get": {
        "operationId": "listMailboxes",
        "summary": "List active Premium mailboxes accessible to the API key",
        "responses": {
          "200": {
            "description": "Account mailboxes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Mailbox"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/mailboxes/{mailboxId}/messages": {
      "get": {
        "operationId": "listMessages",
        "summary": "List inbox messages, newest first",
        "parameters": [
          {
            "name": "mailboxId",
            "in": "path",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true,
            "description": "Mailbox ID."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 25
            },
            "required": false,
            "description": "Page size."
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "required": false,
            "description": "The next_cursor from the preceding page."
          }
        ],
        "responses": {
          "200": {
            "description": "Message page",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "next_cursor"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Message"
                      }
                    },
                    "next_cursor": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/mailboxes/{mailboxId}/messages/{messageId}": {
      "get": {
        "operationId": "getMessage",
        "summary": "Read an inbox message",
        "parameters": [
          {
            "name": "mailboxId",
            "in": "path",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true,
            "description": "Mailbox ID."
          },
          {
            "name": "messageId",
            "in": "path",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true,
            "description": "Message ID."
          }
        ],
        "responses": {
          "200": {
            "description": "Message with body",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MessageDetail"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    },
    "/mailboxes/{mailboxId}/messages/wait": {
      "get": {
        "operationId": "waitForEmail",
        "summary": "Wait for a matching message",
        "description": "Requires an AI & CLI key. Polling uses the account read quota. When no match arrives before the deadline the response has found=false and message=null.",
        "parameters": [
          {
            "name": "mailboxId",
            "in": "path",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "required": true,
            "description": "Mailbox ID."
          },
          {
            "name": "subject",
            "in": "query",
            "description": "Exact subject.",
            "schema": {
              "type": "string",
              "maxLength": 998
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Exact sender address.",
            "schema": {
              "type": "string",
              "format": "email",
              "maxLength": 320
            }
          },
          {
            "name": "after",
            "in": "query",
            "description": "Only match mail received after this time.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "timeout_seconds",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 15
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Match or timeout",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "found",
                    "message"
                  ],
                  "properties": {
                    "found": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "object",
                      "nullable": true,
                      "required": [
                        "id",
                        "from_address",
                        "subject",
                        "received_at"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "from_address": {
                          "type": "string"
                        },
                        "subject": {
                          "type": "string",
                          "nullable": true
                        },
                        "received_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerKey": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Mailbox": {
        "type": "object",
        "required": [
          "id",
          "email",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Message": {
        "type": "object",
        "required": [
          "id",
          "from_address",
          "from_name",
          "to_address",
          "subject",
          "intro",
          "received_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "from_address": {
            "type": "string"
          },
          "from_name": {
            "type": "string",
            "nullable": true
          },
          "to_address": {
            "type": "string"
          },
          "subject": {
            "type": "string",
            "nullable": true
          },
          "intro": {
            "type": "string",
            "nullable": true
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MessageDetail": {
        "type": "object",
        "required": [
          "id",
          "from_address",
          "from_name",
          "to_address",
          "subject",
          "intro",
          "received_at",
          "text_body",
          "html_body"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "from_address": {
            "type": "string"
          },
          "from_name": {
            "type": "string",
            "nullable": true
          },
          "to_address": {
            "type": "string"
          },
          "subject": {
            "type": "string",
            "nullable": true
          },
          "intro": {
            "type": "string",
            "nullable": true
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "text_body": {
            "type": "string",
            "nullable": true
          },
          "html_body": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "request_id"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    },
    "responses": {
      "Error400": {
        "description": "Invalid input",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error401": {
        "description": "Invalid or revoked API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error403": {
        "description": "Active Pro subscription or AI & CLI key required",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error404": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error409": {
        "description": "Address, quota, or idempotency conflict",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error413": {
        "description": "Request body too large",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error429": {
        "description": "Request limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying, when provided.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      },
      "Error500": {
        "description": "Internal error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error503": {
        "description": "Service unavailable",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying, when provided.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      }
    }
  }
}
