从你的服务器读取提交数据
开发者 API 是供你自己的服务器、脚本与工具调用的只读接口。它返回你的工作区已经收到、且仍在保留期内的提交。API 查询不消耗提交额度,也不会改变已读状态或通知状态。
哪些套餐可用
有效的 Starter 或 Builder 套餐包含开发者 API。Free 不包含:API 访问属于付费能力。
每次请求都会重新校验当前的有效付费权益。取消续费后,访问会持续到你已经付款的权益期结束,然后停止。恢复付费后,仍处于有效状态的密钥可以继续使用;已撤销、已过期或因修改密码而失效的密钥无法恢复。
创建与管理密钥
- 在工作区中打开 开发者。
- 为密钥命名,然后选择创建密钥。
- 立即复制完整密钥。它只显示一次,之后无法再次查看——列表里只会保留名称、掩码和日期。
每个工作区最多可同时持有 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 响应头(秒)。请至少等待该时长再重试,避免并发重试风暴。
状态码
| 状态 | 错误码 | 含义 |
|---|---|---|
| 400 | invalid_request / invalid_cursor | 参数或筛选上下文无效,或游标格式错误、与当前筛选不匹配。 |
| 401 | invalid_key | 密钥缺失、格式错误、已撤销、已过期,或账户已关闭。 |
| 403 | plan_required | 工作区当前没有有效的付费权益。 |
| 404 | not_found | 路由不存在,或记录不存在、属于其他工作区、已过保留期。 |
| 405 | method_not_allowed | 仅支持 GET。响应带 Allow: GET。 |
| 429 | rate_limit | 请求过于频繁。请阅读 Retry-After 后等待重试。 |
| 503 | unavailable | 临时不可用或资源竞争。请稍后重试。 |
错误响应为 JSON:{ "error": "…", "code": "…" }。所有响应(包括错误)都使用 Cache-Control: no-store。错误响应不会回显 SQL、凭据、消息正文或内部异常;成功的详情响应会返回你有权读取的完整字段。
保留期与生命周期
API 与应用展示完全一致:记录在自己的删除日期到期后不再返回,升级也无法恢复已删除或已过期的内容。密钥在 365 天后过期;已撤销、已过期或因修改密码而失效的密钥无法重新启用。
妥善保管密钥
密钥只应放在你掌控的可信服务端。不要把它写进公开网页、浏览器代码、分发包或公开仓库——持有密钥的人可以读取本工作区保留期内的全部提交。如果密钥泄露,请在开发者页面撤销并重新创建。
仍需帮助?联系 support@formpostbox.com. 请附上相关文档主题和脱敏后的错误信息,不要发送密钥或访客消息。
浏览全部主题 ↑