Freepost 开发者文档

通过 Freepost 的 REST API、MCP 和 Agent 技能管理草稿,并发布到已连接的社媒账号。

概览

使用 REST 查询托管账号、上传媒体、校验和管理草稿、立即发布或排期,以及查询投递状态。

交互式客户端可通过 OAuth 连接远程 MCP,本地客户端可使用 API 密钥连接 stdio MCP。Freepost 技能提供完整操作流程和各平台的写作指引。

身份验证

工作区所有者可在「设置 → API 密钥」创建密钥。REST 请求需发送 Authorization: Bearer <工作区 API 密钥>。为每个集成单独创建密钥,并按需授予权限和账号访问。

支持 OAuth 的 MCP 客户端会打开 Freepost 登录和授权页面。选择工作区、可访问的账号和需要授予的权限。可在「设置 → 已连接应用」撤销授权。

权限允许的操作
posts:read读取工作区内容和发布投递记录。
posts:write校验、创建、编辑和删除草稿。
publish:write立即发布草稿。
accounts:read查询已授权账号、平台规则和工作区用量。
media:read列出媒体并读取媒体文件。
media:write上传或导入媒体。
schedules:write为草稿排期,或取消尚未发送的排期。
webhooks:manage使用未限制账号的工作区密钥管理 Webhook 并查看投递日志。
analytics:read在弃用期内通过旧版数据分析工具读取工作区摘要。

REST 快速入门

先在 Freepost 连接社媒账号,并在终端设置 FREEPOST_API_KEY。以下示例要求目标账号支持纯文本发布。发布前请查询平台规则、上传所需媒体,并校验草稿。

  1. 列出账号,再把目标账号的 ID 设为 ACCOUNT_ID。

    FREEPOST_API_URL=https://freepost.io
    curl --fail-with-body -sS "$FREEPOST_API_URL/api/v1/accounts" \
      -H "Authorization: Bearer $FREEPOST_API_KEY"
  2. 创建草稿。每份新草稿使用新的 DRAFT_KEY,将返回的 data.id 保存为 POST_ID。

    curl --fail-with-body -sS "$FREEPOST_API_URL/api/v1/posts" \
      -H "Authorization: Bearer $FREEPOST_API_KEY" \
      -H 'Content-Type: application/json' \
      -H "Idempotency-Key: $DRAFT_KEY" \
      -d '{"content":"Hello from Freepost","targetAccounts":["'"$ACCOUNT_ID"'"]}'
  3. 使用新的 PUBLISH_KEY 发布。重试同一次操作时,沿用原来的密钥和请求。用同一个密钥发送变更后的请求会返回 409。

    curl --fail-with-body -sS -X POST "$FREEPOST_API_URL/api/v1/posts/$POST_ID/publish" \
      -H "Authorization: Bearer $FREEPOST_API_KEY" \
      -H "Idempotency-Key: $PUBLISH_KEY"
  4. 如果结果为 pending,将 data.deliveryId 设为 DELIVERY_ID 后轮询投递状态。也可以从草稿目标的 latestPublicationId 找回投递 ID。

    curl --fail-with-body -sS "$FREEPOST_API_URL/api/v1/publications/$DELIVERY_ID" \
      -H "Authorization: Bearer $FREEPOST_API_KEY"

配置 MCP

基于 Streamable HTTP 的远程 MCP

在 MCP 客户端添加以下远程服务器地址,然后登录并授权。程序化集成也可通过工作区 API 密钥访问此地址。

https://freepost.io/api/mcp

本地 stdio MCP

使用 Node.js 22 或更新版本,从 Freepost 源码构建命令行程序。将示例路径替换为本机的绝对路径。

pnpm --filter @freepost/mcp build

Claude Desktop 和 Cursor 的 JSON 配置

{
  "mcpServers": {
    "freepost": {
      "command": "node",
      "args": [
        "/absolute/path/to/freepost/packages/mcp/dist/server.js"
      ],
      "env": {
        "FREEPOST_API_URL": "https://freepost.io",
        "FREEPOST_API_KEY": "YOUR_WORKSPACE_API_KEY"
      }
    }
  }
}

Codex 的 config.toml 配置

请在启动 Codex 的环境中设置 FREEPOST_API_KEY。

[mcp_servers.freepost]
command = "node"
args = ["/absolute/path/to/freepost/packages/mcp/dist/server.js"]
env_vars = ["FREEPOST_API_KEY"]

[mcp_servers.freepost.env]
FREEPOST_API_URL = "https://freepost.io"

接口列表

操作方法路径权限风险级别幂等键
accounts.listGET/api/v1/accountsaccounts:readread无需
usage.getGET/api/v1/usageaccounts:readread无需
platforms.rulesGET/api/v1/platforms/rulesaccounts:readread无需
posts.getGET/api/v1/posts/{id}posts:readread无需
publications.getGET/api/v1/publications/{id}posts:readread无需
media.uploadPOST/api/v1/mediamedia:writedraft无需
posts.validatePOST/api/v1/posts/validateposts:writedraft无需
posts.createPOST/api/v1/postsposts:writedraft必填*
posts.updatePATCH/api/v1/posts/{id}posts:writedraft无需
posts.deleteDELETE/api/v1/posts/{id}posts:writedraft无需
posts.publishPOST/api/v1/posts/{id}/publishpublish:writeexternal必填*
posts.schedulePOST/api/v1/posts/{id}/scheduleschedules:writeexternal必填
schedules.cancelPOST/api/v1/schedules/{id}/cancelschedules:writeexternal无需

* 新集成必须提供。旧版 REST 客户端仍可发送不带幂等键的请求。

OpenAPI JSON

发布结果

结果客户端操作
succeeded平台已确认发布。若响应提供了平台内容 ID 或链接,即可使用。
pendingFreepost 已接收投递。使用投递 ID 轮询,或等待 Webhook。
failed查看 code 和 message。只有 retryable 为 true 时才重试,并按 retryAfter(秒)等待。
unknown先到目标账号核对实际结果,再回 Freepost 确认投递。结果未知时请勿重新发送。

发布节奏与请求限流

每个账号都有已配置的最短发布间隔和单日上限。通过 platforms.rules 查询限制,通过 accounts.list 查询 postsLeftToday 和 nextAllowedPublishAt。凭证也可设置跨账号单日上限,单日计数在 UTC 午夜重置。

默认每分钟允许 120 次读取、30 次写入、5 次发布类请求及 10 次高消耗请求。REST 和 stdio 共用工作区限流计数,远程 MCP 按验证后的凭证计数。REST 触发限流时可能返回 Retry-After 和 X-RateLimit-* 响应头。

所有套餐都包含 Agent 接入。读取和校验不消耗套餐额度。创建草稿与产品界面共享工作区的单日创建额度。免费套餐每月有 20 次外部发布额度,在每月第一天的 UTC 午夜重置。已发送的投递即使结果未知也计入用量。付费套餐没有外部发布月度上限。

调用 GET /api/v1/usage 或 MCP 的 usage_get,查询工作区本月用量、是否执行上限、重置时间和当日剩余内容创建额度。

Webhook

在「设置 → Webhook」订阅事件,也可用 webhooks:manage 权限调用 /api/v1/webhooks。Freepost 会重试失败的投递。解析 JSON 前,请用原始请求字节验证签名。

可订阅事件

  • publication.succeeded
  • publication.failed
  • publication.unknown
  • publication.resolved
  • schedule.dispatched
  • account.needs_reauth

Node.js 签名验证示例

import { createHmac, timingSafeEqual } from "node:crypto";

export async function verifyFreepostWebhook(request, secret) {
  const body = Buffer.from(await request.arrayBuffer());
  const signature = request.headers.get("Freepost-Signature") ?? "";
  const match = /^t=(0|[1-9][0-9]{0,15}),v1=([a-f0-9]{64})$/.exec(signature);
  if (!secret || !match || match[0] !== signature) return null;

  const sentAt = Number(match[1]);
  const now = Math.floor(Date.now() / 1000);
  if (!Number.isSafeInteger(sentAt) || Math.abs(now - sentAt) > 300) return null;

  const expected = createHmac("sha256", secret)
    .update(match[1] + ".")
    .update(body)
    .digest();
  if (!timingSafeEqual(expected, Buffer.from(match[2], "hex"))) return null;
  return JSON.parse(body.toString("utf8"));
}

签名无效时返回 401。通过持久化存储按事件 ID 去重,处理成功后返回 HTTP 2xx。Freepost-Delivery 是 Webhook 投递 ID,Freepost-Event 是事件类型。手动重投会沿用事件 ID。

错误处理

REST 错误包含 error.code 和 error.message,可能附有 error.details。发布响应也可在 data 中返回投递失败结果。

HTTP 状态码原因与下一步
400修正无效的请求参数,或补上必填的幂等键。
401提供有效的 API 密钥,或重新连接远程 MCP 客户端。
402EXTERNAL_PUBLISH_LIMIT_REACHED。升级工作区套餐,或等到下一个 UTC 月。
403检查所需权限、工作区角色和套餐限制。
404此凭证无法读取该资源。请核对 ID 以及工作区或账号权限。
409幂等键已用于其他请求,或资源当前状态与此操作冲突。
410资源或旧版 RPC 已停用。若操作已有投递记录,可继续查询现有投递。
422修正请求。草稿校验问题可能出现在 error.details.problems 中。
429按 Retry-After 或返回的发布节奏间隔等待。
503服务暂时不可用。带幂等键的操作应沿用原请求和幂等键重试。

更新日志

提供 REST v1、远程 MCP、stdio MCP、Agent 技能、带签名的 Webhook 以及外部发布用量查询。

POST /api/v1/mcp/{tool} 自 2026 年 11 月 20 日起弃用,并从 2027 年 1 月 19 日 00:00 UTC 起返回 410。请迁移到远程 MCP、stdio MCP 的标准工具或 REST v1。旧版响应提供 Deprecation、Sunset 和 Link 响应头。

配置 stdio MCP