文档/提交契约与字段

从网站发送表单提交

本指南说明浏览器表单的提交契约,适用于从已获准的网站来源直接向 FormPostbox 表单发送消息。

适用情况

编写或检查自定义 HTML、React、Astro 等浏览器代码时,请参照本指南。需要现成实现时,可打开接入表单,或在表单的连接你的网站面板复制 AI 提示词。

端点与请求编码

向 https://formpostbox.com/f/{formId} 发送 POST 请求,并将路径中的表单 ID 替换为 FormPostbox 表单页显示的 ID。请求体仅支持 application/json 或 application/x-www-form-urlencoded。不支持 multipart 上传或其他内容类型。若页面需要准确显示保存结果或错误,请通过 fetch 携带 Accept: application/json。原生 HTML 表单成功后会重定向;请求被拒绝时会显示 HTML 错误页。

字段与长度限制

请发送由字段名和字符串值组成的数据。业务字段名长度为 1–128 个字符;每次请求最多包含 50 个业务字段。每个值最多 32,768 个字符。编码后的请求体和规范化后的业务字段 JSON 均不得超过 65,536 字节。保留字段 _intent_id 和 cf-turnstile-response 不计入 50 个业务字段。

每次提交都必须包含 _intent_id,长度为 16–128 个字符,用于标识访客发起的一次提交。访客开始填写新消息时生成一个值;请求进行中遇到网络重试时保留并复用它。服务器确认保存后清除该值,下次提交重新生成。

复选框和多选框请使用独立字段名,或显式序列化为字符串,例如 topics=design%2Csupport。不要发送数组、对象、文件或其他非字符串值。当前不支持附件。

允许的来源与可选防护

页面的完整来源必须列在该表单所属网站的允许来源中,协议、主机名和端口都必须一致。来源中不包含页面路径,也不支持通配符。每次重试也会重新检查来源。若页面显示 CORS 或网络错误,请核对工作区显示的允许来源与浏览器地址栏中的协议、主机名和端口。

网站开启 Turnstile 防护时,必须提交一个新的、一次性使用的 cf-turnstile-response 令牌,长度为 1–2,048 个字符。令牌缺失、过期、已使用或验证失败都会导致请求被拒绝。未开启防护的网站不需要此令牌;若附带了长度不超过 2,048 个字符的令牌,服务端会忽略它。私密密钥保存在 FormPostbox 服务端,不会从浏览器代码发送。

读取提交结果

新消息保存成功时返回 HTTP 201,JSON 示例如 {"saved":true,"id":"…","replayed":false,"notification":"queued"}。使用相同意图和相同字段重试时返回 HTTP 200,包含原记录 ID、replayed: true 和 notification: "unchanged";不会创建重复记录,也不会再次消耗额度。如果同一个意图对应不同字段,则返回 409 conflict。要重试,请恢复原字段;开始一条新消息时,先由用户明确发起,再创建新意图。

只有响应中的 saved: true 才代表消息已保存。notification 字段描述独立的邮件流程:新消息已排入邮件通知时为 queued,表单关闭通知时为 off,幂等重试时为 unchanged。消息保存成功不代表邮件已进入收件箱。详情见邮件通知状态。

错误响应

请求被拒绝时,响应格式为 {"saved":false,"error":"…"}。显示成功状态前,请先检查 HTTP 状态码和错误代码:

HTTP代码含义与检查方法
400invalid请求体无效或字段超过限制。请发送仅含命名字符串字段的对象,并检查长度限制。
400origin页面来源未获允许。请在网站设置中核对协议、主机名和端口。
400captchaTurnstile 验证失败。请获取新令牌,并检查组件密钥和主机名。
400paused表单未启用。请在表单列表中启用。
400configuration表单通知收件人已不再通过验证,或请求进行期间防护设置发生变化。请检查表单及网站设置,重新加载表单页面后再试。
404not_found找不到该表单 ID。请从正确的表单页面复制端点。
404expired此意图对应的原记录已删除或超过保留期限。请使用新意图开始一条新提交。
409conflict该意图已用于不同内容。请恢复原请求内容后重试;或者由用户明确开始新消息,再为其生成新意图。
413too_large请求体超过 65,536 字节。请减少文本或字段数量。
415unsupported内容类型不受支持。请使用 JSON 或 URL 编码的表单数据。
429quota工作区本 UTC 月提交额度已用完。请查看限制与额度。
429rate_limit请求频率暂时过高。请稍等后重试。
503unavailable接收服务暂时繁忙。请稍后使用相同意图和内容重试。

常见问题

可以使用 Developer API 密钥来提交吗?不可以。此端点供浏览器直接接入,并依据页面来源进行校验;不接受 API 密钥,也不需要服务端代理。Developer API 密钥用于服务端只读访问保留期内的提交记录。

在哪里查看已保存的消息?打开收件箱并选择一条消息,可查看字段内容和独立的通知时间线。

相关指南:代码示例、来源与验证检查、常见错误。

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

浏览全部主题 ↑