文档/开发者 API
开发者 API

从你的服务器读取提交数据

开发者 API 是供你自己的服务器、脚本与工具调用的只读接口。它返回你的工作区已经收到、且仍在保留期内的提交。API 查询不消耗提交额度,也不会改变已读状态或通知状态。

哪些套餐可用

有效的 Starter 或 Builder 套餐包含开发者 API。Free 不包含:API 访问属于付费能力。

每次请求都会重新校验当前的有效付费权益。取消续费后,访问会持续到你已经付款的权益期结束,然后停止。恢复付费后,仍处于有效状态的密钥可以继续使用;已撤销、已过期或因修改密码而失效的密钥无法恢复。

创建与管理密钥

  1. 在工作区中打开 开发者。
  2. 为密钥命名,然后选择创建密钥。
  3. 立即复制完整密钥。它只显示一次,之后无法再次查看——列表里只会保留名称、掩码和日期。

每个工作区最多可同时持有 10 个有效密钥,密钥会在创建 365 天后自动过期。轮换方式:创建新密钥、更新你的服务器,然后撤销旧密钥。撤销会立即在所有服务器上生效。修改或重置密码会撤销全部密钥;注销账户会撤销密钥并立即阻止使用;备份恢复后,此前发出的所有密钥都会失效。

认证

在每次请求中以 Bearer 令牌发送密钥。密钥固定绑定一个工作区和只读权限(submissions:read),不能创建、修改或删除任何内容,也不能用于浏览器接口或管理接口。

Authorization: Bearer YOUR_API_KEY

查询提交列表

GET https://formpostbox.com/api/v1/submissions

查询参数:

  • formId — 只返回某个表单(UUID)的提交。
  • from / to — UTC 时间范围。可以使用日历日期(YYYY-MM-DD)或 UTC 时间戳(如 2026-10-08T09:30:00Z)。from 为包含边界;to 为排除边界。只写日期的 to 表示覆盖整个 UTC 日。
  • limit — 每页条数,1–100,默认 25。
  • cursor — 来自 nextCursor 的不透明游标。翻页期间请保持筛选条件不变;筛选变化后旧游标会被拒绝。

列表中的每一项包含 id、formId、formName、siteName、receivedAt 与 retentionEndsAt(UTC ISO 8601)、reviewed、notificationStatus,以及截断的 summary(title、preview)。摘要只是预览——完整提交字段请调用详情接口。

{
  "data": [
    {
      "id": "b1f0c2f4-…",
      "formId": "7f3c5b12-…",
      "formName": "Contact form",
      "siteName": "northstar.example",
      "receivedAt": "2026-10-08T09:30:00.000Z",
      "retentionEndsAt": "2027-10-08T09:30:00.000Z",
      "reviewed": false,
      "notificationStatus": "delivered",
      "summary": { "title": "Question about pricing", "preview": "Hi, I would like to know…" }
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

单条提交详情

GET https://formpostbox.com/api/v1/submissions/{submissionId}

详情响应会附带与提交时一致的完整 fields 对象。已删除的记录、正文已清除的记录、已过删除日期的记录以及已注销账户都不会返回;查询其他工作区的记录统一返回 404,与记录不存在完全一致。

示例:curl

curl -s "https://formpostbox.com/api/v1/submissions?limit=25&from=2026-10-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

示例:服务端 JavaScript

const apiKey = process.env.FORMPOSTBOX_API_KEY;

export async function listSubmissions(formId) {
  const url = new URL('https://formpostbox.com/api/v1/submissions');
  url.searchParams.set('formId', formId);
  url.searchParams.set('limit', '100');

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  if (!response.ok) {
    const { code } = await response.json();
    throw new Error(`Developer API error ${response.status}: ${code}`);
  }
  return response.json();
}

遍历全部提交

上面的 listSubmissions 只取一页。要取得全部结果,请一直传回 nextCursor,直到 hasMore 为 false。保持筛选不变,不要自行构造或解码游标。下面的异步迭代器按页读取;若返回 429,按 Retry-After 等待后再执行,避免并发重试。

const apiKey = process.env.FORMPOSTBOX_API_KEY;
async function* allSubmissions(formId) {
  let cursor;
  do {
    const url = new URL('https://formpostbox.com/api/v1/submissions');
    url.searchParams.set('formId', formId);
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);
    const response = await fetch(url, {headers: {Authorization: `Bearer ${apiKey}`}});
    if (!response.ok) throw new Error(`HTTP ${response.status}; Retry-After: ${response.headers.get('Retry-After')}`);
    const page = await response.json();
    yield* page.data;
    cursor = page.hasMore ? page.nextCursor : null;
  } while (cursor);
}
for await (const submission of allSubmissions('YOUR_FORM_ID')) {
  console.log(submission.id);
}

日期示例:from=2026-10-01&to=2026-10-16 包含 10 月 16 日整个 UTC 日;而 to=2026-10-16T00:00:00Z 不包含该时间点之后的数据。下载 OpenAPI YAML。

请求限流

  • 每个工作区每分钟 60 次请求,由其全部密钥共享。
  • 每个密钥每分钟 30 次请求。创建更多密钥不会提高工作区上限。
  • 创建、查看和撤销密钥在工作区内另有独立限流。

达到限流时,API 返回 429,并附带 Retry-After 响应头(秒)。请至少等待该时长再重试,避免并发重试风暴。

状态码

状态错误码含义
400invalid_request / invalid_cursor参数或筛选上下文无效,或游标格式错误、与当前筛选不匹配。
401invalid_key密钥缺失、格式错误、已撤销、已过期,或账户已关闭。
403plan_required工作区当前没有有效的付费权益。
404not_found路由不存在,或记录不存在、属于其他工作区、已过保留期。
405method_not_allowed仅支持 GET。响应带 Allow: GET。
429rate_limit请求过于频繁。请阅读 Retry-After 后等待重试。
503unavailable临时不可用或资源竞争。请稍后重试。

错误响应为 JSON:{ "error": "…", "code": "…" }。所有响应(包括错误)都使用 Cache-Control: no-store。错误响应不会回显 SQL、凭据、消息正文或内部异常;成功的详情响应会返回你有权读取的完整字段。

保留期与生命周期

API 与应用展示完全一致:记录在自己的删除日期到期后不再返回,升级也无法恢复已删除或已过期的内容。密钥在 365 天后过期;已撤销、已过期或因修改密码而失效的密钥无法重新启用。

妥善保管密钥

密钥只应放在你掌控的可信服务端。不要把它写进公开网页、浏览器代码、分发包或公开仓库——持有密钥的人可以读取本工作区保留期内的全部提交。如果密钥泄露,请在开发者页面撤销并重新创建。

仍需帮助?联系 support@formpostbox.com. 请附上相关文档主题和脱敏后的错误信息,不要发送密钥或访客消息。

浏览全部主题 ↑