{
  "openapi": "3.1.0",
  "info": {
    "title": "NexMask OpenAPI",
    "version": "1.0.0",
    "description": "NexMask 邮箱、邮件与用户信息接口。无参数查询使用 GET；需要业务参数或会产生状态变更的接口使用 JSON 请求体。"
  },
  "servers": [{ "url": "https://app.nexmask.net" }],
  "security": [{ "apiKey": [] }],
  "components": {
    "parameters": {
      "AcceptLanguage": {
        "name": "Accept-Language", "in": "header", "required": false,
        "description": "Language for success, business errors and HTTP errors. Supports zh-CN, zh-TW, en-US and q weights. If omitted or blank, use the API Key owner language; if the account is unidentified, use en-US. Invalid or unsupported headers use en-US. X-Language and website sessions do not override this setting.",
        "schema": { "type": "string" }, "example": "zh-CN, en-US;q=0.8"
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey", "in": "header", "name": "apiKey",
        "description": "Copy your API Key from Personal space or this documentation page while signed in. Send apiKey: YOUR_API_KEY on every request, using the raw key without a Bearer prefix. OpenAPI does not read API Keys from Authorization, JSON bodies, URL queries or website cookies. Active VIP membership is required. Resetting the key invalidates the old one; update all integrations. Start with GET /openapi/v1/user/info.cgi, a read-only request that does not create mailboxes or deduct credits. Keep keys on a trusted backend, not in public client code or shared logs."
      }
    },
    "schemas": {
      "Result": {
        "type": "object",
        "required": ["code", "msg"],
        "properties": {
          "code": {
            "type": "integer",
            "description": "站内接口与 OpenAPI 共用的稳定响应码；0 表示成功，负数表示可识别的业务错误",
            "enum": [0, -1001, -1006, -1100, -1101, -1102, -1208, -1210, -1300, -1400, -1401, -1403, -1404, -1405, -1407, -1408, -1409, -1410, -1411, -1412, -1700]
          },
          "msg": { "type": "string" },
          "data": {}
        }
      },
      "PageRequest": {
        "type": "object",
        "properties": {
          "page": { "type": "integer", "minimum": 1, "default": 1 },
          "keyword": { "type": "string", "maxLength": 100 }
        }
      },
      "MailListRequest": {
        "type": "object",
        "properties": {
          "mailboxId": { "type": "integer", "format": "int64", "minimum": 1, "description": "可选；传入时仅查询当前用户的指定邮箱，不传时查询当前用户全部邮箱" },
          "page": { "type": "integer", "minimum": 1, "default": 1 },
          "keyword": { "type": "string", "maxLength": 100 }
        }
      },
      "MailboxCreateRequest": {
        "type": "object",
        "properties": {
          "prefix": { "type": "string", "description": "留空时随机分配" },
          "domainId": { "type": "integer", "format": "int64", "description": "可选；留空时从公共域名和登录域名中随机选择" },
          "durationHours": { "type": "integer", "minimum": 0, "default": 1, "description": "0 按 1 小时处理；其他时长必须匹配可用套餐，1 小时未配置时免费" }
        }
      },
      "RelayMailboxCreateRequest": {
        "type": "object",
        "required": ["suffix", "durationHours"],
        "properties": {
          "suffix": { "type": "string", "enum": ["gmail.com", "outlook.com", "googlemail.com", "hotmail.com"], "description": "精确选择后缀，不自动替换；不需要 prefix 或 domainId" },
          "durationHours": { "type": "integer", "minimum": 0, "description": "必填且不可为 null；0 按 1 小时处理；匹配 MAIL_PRICE 套餐，计费同临时邮箱，1 小时未配置时免费" }
        },
        "example": { "suffix": "gmail.com", "durationHours": 24 }
      },
      "MailboxView": {
        "type": "object",
        "required": ["id", "email", "receivedCount", "expiresAt", "guest"],
        "properties": {
          "id": { "type": "integer", "format": "int64" },
          "email": { "type": "string", "format": "email" },
          "receivedCount": { "type": "integer", "format": "int64" },
          "expiresAt": { "type": "string", "format": "date-time" },
          "state": { "type": "integer" },
          "uuid": { "type": ["string", "null"] },
          "guest": { "type": "boolean", "const": false }
        }
      },
      "MailboxCreateResponse": {
        "allOf": [
          { "$ref": "#/components/schemas/Result" },
          { "type": "object", "properties": { "data": { "oneOf": [{ "$ref": "#/components/schemas/MailboxView" }, { "type": "null" }] } } }
        ]
      },
      "Domain": {
        "type": "object",
        "required": ["id", "domain", "type", "ownerId", "mailboxOccupy", "mailboxCount", "state"],
        "properties": {
          "id": { "type": "integer", "format": "int64" },
          "domain": { "type": "string", "description": "收信域名" },
          "type": { "type": "integer", "enum": [0, 1, 2, 3], "description": "0 公共、1 登录、2 会员、3 私有" },
          "ownerId": { "type": "integer", "format": "int64", "description": "系统域名为 0，私有域名为所属用户 ID" },
          "mailboxOccupy": { "type": "integer", "format": "int64", "description": "已占用邮箱数量" },
          "seq": { "type": "integer", "format": "int64" },
          "mailboxCount": { "type": "integer", "format": "int64", "description": "邮箱池总量" },
          "mailCount": { "type": "integer", "format": "int64" },
          "state": { "type": "integer", "const": 0, "description": "返回列表中的域名均为可用状态" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "DomainListResponse": {
        "type": "object",
        "required": ["code", "msg", "data"],
        "properties": {
          "code": { "type": "integer", "const": 0 },
          "msg": { "type": "string" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }
        }
      },
      "UsAddressGenerateRequest": {
        "allOf": [
          { "$ref": "#/components/schemas/MailboxCreateRequest" },
          {
            "type": "object",
            "properties": {
              "stateCode": {
                "type": "string",
                "pattern": "^[A-Za-z]{2}$",
                "description": "可选 USPS 两位州代码；留空时随机选择州"
              }
            }
          }
        ]
      },
      "UsAddressResult": {
        "type": "object",
        "required": ["mailboxId", "email", "mailboxDomainId", "firstName", "lastName", "gender", "phone", "streetAddress", "city", "stateName", "stateCode", "zipCode", "latitude", "longitude", "fullAddress"],
        "properties": {
          "mailboxId": { "type": "integer", "format": "int64", "description": "已创建邮箱的记录 ID" },
          "email": { "type": "string", "format": "email", "description": "已创建的临时邮箱地址" },
          "mailboxDomainId": { "type": "integer", "format": "int64", "description": "邮箱所属域名 ID" },
          "firstName": { "type": "string" },
          "lastName": { "type": "string" },
          "gender": { "type": "string" },
          "phone": { "type": "string", "description": "按地址所属州选择区号后随机生成的 NANPA 格式电话号码" },
          "streetAddress": { "type": "string" },
          "city": { "type": "string" },
          "stateName": { "type": "string" },
          "stateCode": { "type": "string" },
          "zipCode": { "type": "string" },
          "latitude": { "type": "number" },
          "longitude": { "type": "number" },
          "fullAddress": { "type": "string" }
        }
      },
      "UsAddressResponse": {
        "type": "object",
        "required": ["code", "msg", "data"],
        "properties": {
          "code": { "type": "integer", "const": 0 },
          "msg": { "type": "string" },
          "data": { "$ref": "#/components/schemas/UsAddressResult" }
        }
      },
      "IdRequest": {
        "type": "object",
        "required": ["id"],
        "properties": { "id": { "type": "integer", "format": "int64" } }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "API Key 缺失或无效",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "example": { "code": -1210, "msg": "API Key无效", "data": null } } }
      },
      "VipRequired": {
        "description": "未开通会员或会员已过期",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" }, "example": { "code": -1300, "msg": "需要开通有效会员", "data": null } } }
      }
    }
  },
  "paths": {
    "/openapi/v1/mailbox/create.cgi": {
      "parameters": [{ "$ref": "#/components/parameters/AcceptLanguage" }],
      "post": {
        "summary": "创建邮箱",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxCreateRequest" } } } },
        "responses": { "200": { "description": "业务结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/VipRequired" } }
      }
    },
    "/openapi/v1/relay/mailbox/create.cgi": {
      "parameters": [{ "$ref": "#/components/parameters/AcceptLanguage" }],
      "post": {
        "summary": "创建主流邮箱",
        "description": "独立创建接口，需要有效 apiKey 和有效 VIP。套餐、会员价、积分流水与临时邮箱一致。返回相同的 MsgEntity<MailboxView>；使用 id 作为 mailboxId 调用邮件列表，或使用已有邮箱列表和邮件详情接口。不续费、不召回、不切换网页 Session。重复调用将申请新邮箱并计费。后缀错误 -1100，时长错误 -1405，库存不足 -1407，积分不足 -1208；失败回滚库存、邮箱和积分。",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelayMailboxCreateRequest" } } } },
        "responses": {
          "200": { "description": "业务结果；返回结构与临时邮箱创建接口一致", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailboxCreateResponse" }, "example": { "code": 0, "msg": "Success", "data": { "id": 1024, "email": "example+10ab@gmail.com", "receivedCount": 0, "expiresAt": "2026-10-06T10:00:00.000+00:00", "state": 0, "uuid": null, "guest": false } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/VipRequired" }
        }
      }
    },
    "/openapi/v1/domain/list.cgi": {
      "parameters": [{ "$ref": "#/components/parameters/AcceptLanguage" }],
      "get": {
        "summary": "查询当前用户可用域名",
        "description": "一次读取全部域名后在业务代码中组合公共域名、登录域名、当前用户私有域名，以及有效会员可用的会员域名。",
        "responses": { "200": { "description": "业务结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/VipRequired" } }
      }
    },
    "/openapi/v1/tools/us_address/generate.cgi": {
      "parameters": [{ "$ref": "#/components/parameters/AcceptLanguage" }],
      "post": {
        "summary": "创建临时邮箱并生成随机美国地址资料",
        "description": "沿用邮箱创建接口的套餐、积分和域名权限规则，邮箱创建成功后返回一组指定州或随机州的公开数据地址与随机身份资料。",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsAddressGenerateRequest" } } } },
        "responses": { "200": { "description": "业务结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsAddressResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/VipRequired" } }
      }
    },
    "/openapi/v1/mail/list.cgi": {
      "parameters": [{ "$ref": "#/components/parameters/AcceptLanguage" }],
      "post": {
        "summary": "分页查询邮件列表",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailListRequest" } } } },
        "responses": { "200": { "description": "业务结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/VipRequired" } }
      }
    },
    "/openapi/v1/mail/detail.cgi": {
      "parameters": [{ "$ref": "#/components/parameters/AcceptLanguage" }],
      "post": {
        "summary": "查询邮件详情",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdRequest" } } } },
        "responses": { "200": { "description": "业务结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/VipRequired" } }
      }
    },
    "/openapi/v1/user/info.cgi": {
      "parameters": [{ "$ref": "#/components/parameters/AcceptLanguage" }],
      "get": {
        "summary": "查询用户信息",
        "responses": { "200": { "description": "业务结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/VipRequired" } }
      }
    },
    "/openapi/v1/mailbox/list.cgi": {
      "parameters": [{ "$ref": "#/components/parameters/AcceptLanguage" }],
      "post": {
        "summary": "分页查询邮箱列表",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageRequest" } } } },
        "responses": { "200": { "description": "业务结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Result" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/VipRequired" } }
      }
    }
  }
}