{
  "info": {
    "name": "MailDock 邮箱接码 API v1",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "description": "在私有环境设置 api_key。默认只读；下单与取消分别需要启用 enable_order_requests / enable_cancel_requests。下单会冻结余额并在交付时扣费，禁止无意运行购买；重试保持相同幂等键和参数。指南：https://mail.jqiudata.com/docs/"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{api_key}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://mail.jqiudata.com",
      "type": "string"
    },
    {
      "key": "search",
      "value": "",
      "type": "string"
    },
    {
      "key": "domain",
      "value": "",
      "type": "string"
    },
    {
      "key": "page",
      "value": "1",
      "type": "string"
    },
    {
      "key": "product_id",
      "value": "",
      "type": "string"
    },
    {
      "key": "max_price",
      "value": "",
      "type": "string"
    },
    {
      "key": "idempotency_key",
      "value": "",
      "type": "string"
    },
    {
      "key": "order_id",
      "value": "",
      "type": "string"
    },
    {
      "key": "enable_order_requests",
      "value": "false",
      "type": "string"
    },
    {
      "key": "enable_cancel_requests",
      "value": "false",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "查询可售商品",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/v1/products?search={{search}}&domain={{domain}}&page={{page}}",
        "description": "仅返回已上架且最近库存大于零的商品；按名称、邮箱类型排序。报价通常每 2 分钟刷新，超过 5 分钟会阻止新下单。库存与报价可能在下单前变化。"
      },
      "response": [
        {
          "name": "查询可售商品 200",
          "originalRequest": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{base_url}}/v1/products?search={{search}}&domain={{domain}}&page={{page}}",
            "description": "仅返回已上架且最近库存大于零的商品；按名称、邮箱类型排序。报价通常每 2 分钟刷新，超过 5 分钟会阻止新下单。库存与报价可能在下单前变化。"
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"items\": [\n    {\n      \"id\": \"87c21967-8aa9-4496-9913-fb24b7a77691\",\n      \"service\": \"ka\",\n      \"name\": \"Shopee\",\n      \"domain\": \"gmail.com\",\n      \"price\": \"0.216\",\n      \"unit\": \"余额点\",\n      \"stock\": 100,\n      \"quoted_at\": \"2026-11-14T10:00:00+00:00\"\n    }\n  ],\n  \"page\": 1,\n  \"page_size\": 50,\n  \"total\": 1\n}"
        }
      ]
    },
    {
      "name": "查询钱包余额",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/v1/balance",
        "description": "网页与 API 共用账户余额。先冻结实际售价，验证码交付时扣费，确认未交付才释放冻结。"
      },
      "response": [
        {
          "name": "查询钱包余额 200",
          "originalRequest": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{base_url}}/v1/balance",
            "description": "网页与 API 共用账户余额。先冻结实际售价，验证码交付时扣费，确认未交付才释放冻结。"
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"available\": \"10\",\n  \"frozen\": \"0\",\n  \"unit\": \"余额点\"\n}"
        }
      ]
    },
    {
      "name": "申请邮箱",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          },
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Idempotency-Key",
            "value": "{{idempotency_key}}"
          }
        ],
        "url": "{{base_url}}/v1/mail-orders",
        "description": "202 仅表示订单已创建且余额已冻结，不代表邮箱已分配。用返回的订单 ID 轮询。200 表示相同幂等请求返回既有订单。max_price 是售价上限，实际冻结 order.price。",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"product_id\": \"{{product_id}}\",\n  \"max_price\": \"{{max_price}}\"\n}",
          "options": {
            "raw": {
              "language": "json"
            }
          }
        }
      },
      "response": [
        {
          "name": "申请邮箱 202",
          "originalRequest": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Idempotency-Key",
                "value": "{{idempotency_key}}"
              }
            ],
            "url": "{{base_url}}/v1/mail-orders",
            "description": "202 仅表示订单已创建且余额已冻结，不代表邮箱已分配。用返回的订单 ID 轮询。200 表示相同幂等请求返回既有订单。max_price 是售价上限，实际冻结 order.price。",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"product_id\": \"{{product_id}}\",\n  \"max_price\": \"{{max_price}}\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "status": "Accepted",
          "code": 202,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"order\": {\n    \"id\": \"25d47c44-59dc-4c54-a04f-dc5fd5eef222\",\n    \"service\": \"ka\",\n    \"service_name\": \"Shopee\",\n    \"domain\": \"gmail.com\",\n    \"email\": null,\n    \"state\": \"creating\",\n    \"state_label\": \"正在分配\",\n    \"price\": \"0.216\",\n    \"unit\": \"余额点\",\n    \"settlement\": \"reserved\",\n    \"code\": null,\n    \"created_at\": \"2026-11-14T10:00:10+00:00\",\n    \"expires_at\": null,\n    \"received_at\": null\n  },\n  \"created\": true\n}"
        },
        {
          "name": "申请邮箱 200",
          "originalRequest": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              },
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Idempotency-Key",
                "value": "{{idempotency_key}}"
              }
            ],
            "url": "{{base_url}}/v1/mail-orders",
            "description": "202 仅表示订单已创建且余额已冻结，不代表邮箱已分配。用返回的订单 ID 轮询。200 表示相同幂等请求返回既有订单。max_price 是售价上限，实际冻结 order.price。",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"product_id\": \"{{product_id}}\",\n  \"max_price\": \"{{max_price}}\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"order\": {\n    \"id\": \"25d47c44-59dc-4c54-a04f-dc5fd5eef222\",\n    \"service\": \"ka\",\n    \"service_name\": \"Shopee\",\n    \"domain\": \"gmail.com\",\n    \"email\": null,\n    \"state\": \"creating\",\n    \"state_label\": \"正在分配\",\n    \"price\": \"0.216\",\n    \"unit\": \"余额点\",\n    \"settlement\": \"reserved\",\n    \"code\": null,\n    \"created_at\": \"2026-11-14T10:00:10+00:00\",\n    \"expires_at\": null,\n    \"received_at\": null\n  },\n  \"created\": false\n}"
        }
      ],
      "event": [
        {
          "listen": "prerequest",
          "script": {
            "type": "text/javascript",
            "exec": [
              "if (pm.variables.get('enable_order_requests') !== 'true') { pm.execution.skipRequest(); }",
              "for (const key of ['product_id', 'max_price', 'idempotency_key']) {",
              "  if (!pm.variables.get(key)) { pm.execution.skipRequest(); throw new Error('请先填写 ' + key); }",
              "}",
              "// 不在重试时生成或替换 idempotency_key；先在业务数据库保存原请求。"
            ]
          }
        },
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "if (pm.response.code === 200 || pm.response.code === 202) {",
              "  const order = pm.response.json().order;",
              "  if (order && order.id) pm.collectionVariables.set('order_id', order.id);",
              "}"
            ]
          }
        }
      ]
    },
    {
      "name": "查询订单列表",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/v1/mail-orders?page={{page}}",
        "description": "仅当前账户订单，按创建时间倒序。每项为完整 Order，含邮箱与验证码；多笔订单可合并轮询列表。不支持 state 过滤。"
      },
      "response": [
        {
          "name": "查询订单列表 200",
          "originalRequest": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{base_url}}/v1/mail-orders?page={{page}}",
            "description": "仅当前账户订单，按创建时间倒序。每项为完整 Order，含邮箱与验证码；多笔订单可合并轮询列表。不支持 state 过滤。"
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"items\": [\n    {\n      \"id\": \"25d47c44-59dc-4c54-a04f-dc5fd5eef222\",\n      \"service\": \"ka\",\n      \"service_name\": \"Shopee\",\n      \"domain\": \"gmail.com\",\n      \"email\": \"sample@example.com\",\n      \"state\": \"received\",\n      \"state_label\": \"验证码已送达\",\n      \"price\": \"0.216\",\n      \"unit\": \"余额点\",\n      \"settlement\": \"captured\",\n      \"code\": \"001234\",\n      \"created_at\": \"2026-11-14T10:00:10+00:00\",\n      \"expires_at\": \"2026-11-14T10:10:15+00:00\",\n      \"received_at\": \"2026-11-14T10:01:00+00:00\"\n    }\n  ],\n  \"page\": 1,\n  \"page_size\": 50,\n  \"total\": 1\n}"
        }
      ]
    },
    {
      "name": "查询邮箱与验证码",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/v1/mail-orders/{{order_id}}",
        "description": "邮箱尚未分配时 email 为 null；验证码尚未交付时 code 为 null。建议每 5 秒查询一次；先检查 code，再处理 state。"
      },
      "response": [
        {
          "name": "查询邮箱与验证码 200",
          "originalRequest": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{base_url}}/v1/mail-orders/{{order_id}}",
            "description": "邮箱尚未分配时 email 为 null；验证码尚未交付时 code 为 null。建议每 5 秒查询一次；先检查 code，再处理 state。"
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"order\": {\n    \"id\": \"25d47c44-59dc-4c54-a04f-dc5fd5eef222\",\n    \"service\": \"ka\",\n    \"service_name\": \"Shopee\",\n    \"domain\": \"gmail.com\",\n    \"email\": \"sample@example.com\",\n    \"state\": \"received\",\n    \"state_label\": \"验证码已送达\",\n    \"price\": \"0.216\",\n    \"unit\": \"余额点\",\n    \"settlement\": \"captured\",\n    \"code\": \"001234\",\n    \"created_at\": \"2026-11-14T10:00:10+00:00\",\n    \"expires_at\": \"2026-11-14T10:10:15+00:00\",\n    \"received_at\": \"2026-11-14T10:01:00+00:00\"\n  }\n}"
        }
      ],
      "event": [
        {
          "listen": "prerequest",
          "script": {
            "type": "text/javascript",
            "exec": [
              "if (!pm.variables.get('order_id')) { pm.execution.skipRequest(); }"
            ]
          }
        }
      ]
    },
    {
      "name": "取消未交付订单",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/v1/mail-orders/{{order_id}}/cancel",
        "description": "无需请求体。HTTP 200 可能返回 cancel_requested，须继续查询至 canceled/released。重复取消已取消、失败或取消中的订单返回当前订单；已交付或待核对返回 409。取消与收码并发时可能仍交付并扣费。"
      },
      "response": [
        {
          "name": "取消未交付订单 200",
          "originalRequest": {
            "method": "POST",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{base_url}}/v1/mail-orders/{{order_id}}/cancel",
            "description": "无需请求体。HTTP 200 可能返回 cancel_requested，须继续查询至 canceled/released。重复取消已取消、失败或取消中的订单返回当前订单；已交付或待核对返回 409。取消与收码并发时可能仍交付并扣费。"
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"order\": {\n    \"id\": \"25d47c44-59dc-4c54-a04f-dc5fd5eef222\",\n    \"service\": \"ka\",\n    \"service_name\": \"Shopee\",\n    \"domain\": \"gmail.com\",\n    \"email\": \"sample@example.com\",\n    \"state\": \"cancel_requested\",\n    \"state_label\": \"取消处理中\",\n    \"price\": \"0.216\",\n    \"unit\": \"余额点\",\n    \"settlement\": \"reserved\",\n    \"code\": null,\n    \"created_at\": \"2026-11-14T10:00:10+00:00\",\n    \"expires_at\": null,\n    \"received_at\": null\n  }\n}"
        }
      ],
      "event": [
        {
          "listen": "prerequest",
          "script": {
            "type": "text/javascript",
            "exec": [
              "if (!pm.variables.get('order_id')) { pm.execution.skipRequest(); }",
              "if (pm.variables.get('enable_cancel_requests') !== 'true') { pm.execution.skipRequest(); }"
            ]
          }
        }
      ]
    },
    {
      "name": "查询钱包流水",
      "request": {
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json"
          }
        ],
        "url": "{{base_url}}/v1/transactions?page={{page}}",
        "description": "仅当前账户流水，按流水 ID 倒序。用 available_delta / frozen_delta 对账，不要把 reserve 与 capture 的 amount 重复计为消费。"
      },
      "response": [
        {
          "name": "查询钱包流水 200",
          "originalRequest": {
            "method": "GET",
            "header": [
              {
                "key": "Accept",
                "value": "application/json"
              }
            ],
            "url": "{{base_url}}/v1/transactions?page={{page}}",
            "description": "仅当前账户流水，按流水 ID 倒序。用 available_delta / frozen_delta 对账，不要把 reserve 与 capture 的 amount 重复计为消费。"
          },
          "status": "OK",
          "code": 200,
          "_postman_previewlanguage": "json",
          "header": [
            {
              "key": "Content-Type",
              "value": "application/json"
            }
          ],
          "body": "{\n  \"items\": [\n    {\n      \"id\": 1001,\n      \"kind\": \"reserve\",\n      \"amount\": \"-0.216\",\n      \"available_delta\": \"-0.216\",\n      \"frozen_delta\": \"0.216\",\n      \"available_after\": \"9.784\",\n      \"frozen_after\": \"0.216\",\n      \"note\": \"订单余额冻结\",\n      \"created_at\": \"2026-11-14T10:00:10+00:00\"\n    }\n  ],\n  \"page\": 1,\n  \"page_size\": 50,\n  \"total\": 1\n}"
        }
      ]
    }
  ]
}