GoShipFast logoGoShipFast

邮件

邮件 API

注册确认、magic link、收据、告警，你产品发出的邮件理应走同一个已验证域名，出现在同一份追踪记录里。这个 API 就是为此准备的一小块朴素的 REST 接口。

鉴权

在邮件 → 接入 → API 里创建密钥。密钥有名字（每个环境或每个集成一把），完整内容只在创建时显示一次，可以单独吊销；创建时间和上次使用时间都有记录，废弃的密钥一眼就能认出来。

请求时作为 bearer token 携带，指向以下 Base URL：

Authorization: Bearer gsf_live_...
Base URL: https://goshipfast.com/api/v1

发送

POST /emails，参数包括 from（必须是已验证域名下的地址）、to、subject，正文用 html 或者用 templateId 加 variables 填充合并字段，二选一。可选项有 replyTo 和 Idempotency-Key 请求头：网络需要重试几次就重试几次，邮件只会发出一封。

调用成功返回 202，带消息 id 和 queued 状态。之后：

  • GET /emails/:id：查询投递生命周期，queued → sent → opened / clicked，或带原因的 bounced / failed。

每次 API 发送同样会出现在追踪 → 记录里，调试所需的信息都摆在界面上，无需去翻日志。

联系人与事件

  • POST /contacts：新增或更新一个收件人（邮箱加属性）。DELETE /contacts/:email 移除。
  • POST /events：上报发生了什么（"user_signed_up"、"trial_ending"）。事件是任务的触发侧：配置为监听某个事件的自动化，会把它的邮件序列发给那位联系人。产品生命周期邮件（新手引导、召回）就这样跑起来，你的代码对序列一无所知也没关系：应用只负责陈述事实，任务决定这些事实配得上哪些邮件。

限制与错误

  • 速率限制：每把密钥每分钟 120 个请求。
  • 发送量：API 发送与其他发送共用套餐配额，包括那条保护发件信誉的每日上限。收到 429 或配额错误，正确反应是放慢速度，加倍重试只会更糟。
  • 错误码都符合惯例：401 密钥无效，403 域名未验证或资源无权访问，422 校验失败并附字段级说明。

产品内的接入指南 tab（邮件 → 接入 → 接入指南）有完整参考，附可运行的 Node 示例和收件 webhook 的验签方法。

一套清爽的集成

  1. 验证一个发件域名；每个环境创建一把密钥。
  2. 事务邮件统一走 POST /emails，带上幂等键。
  3. 在产品的生命周期节点发出 POST /events，哪怕还没有任务用到它们。触发器分文不费，等你哪天搭好序列，当天就能用。
  4. 密钥只放在服务端；它授权以你品牌的名义发信。