EterMail API（v1）

用于从您的服务端把用户与行为数据同步到 EterMail 的某个项目。字段兼容 Segment 规范，SaaS 产品与移动 App 均通过这套接口接入。

鉴权

在「项目设置 → API 密钥」中生成服务端（sk_）密钥。密钥只显示一次，且只能在服务端使用，请勿放入浏览器或 App。密钥本身决定写入哪个项目；也支持 Segment 风格的 Basic 认证（用户名为密钥，密码留空）。

Authorization: Bearer sk_…

通用规则

• messageId 必填，同一项目内唯一；重复请求返回 {"ok":true,"duplicate":true}，可安全重试。
• timestamp 可选（ISO 8601），用于补录历史数据。
• userId（您系统中的用户 ID）与 email 至少提供一个，userId 优先作为身份。
• 每个密钥每分钟 600 次请求，超出返回 429 与 Retry-After；请求体上限 1 MB。

POST /api/v1/identify

创建或更新联系人。traits 中 firstName、lastName、locale、timezone 写入固定字段（没有 locale 时 language 或 lang 也写入语言；用 de、pt-BR 这样的标签），其余作为自定义属性。consent 可选：订阅时必须提供 evidence，说明对方何时、如何同意；对方曾退订后，API 不能重新订阅。

curl https://etermail.ai/api/v1/identify \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "u_123",
    "messageId": "4f9c…",
    "traits": { "email": "[email protected]", "firstName": "Ann", "plan": "pro" },
    "consent": { "topic": "marketing", "status": "subscribed",
      "evidence": { "form": "signup", "checkbox": true } }
  }'

POST /api/v1/track

记录一个行为事件，用于分群、效果归因，以及触发「自定义事件」类型的自动化流程（例如试用开始后的引导邮件）。

{ "userId": "u_123", "event": "Trial Started",
  "properties": { "plan": "pro" }, "messageId": "9a1e…" }

POST /api/v1/batch

一次最多 500 条 identify / track，逐条处理并返回 results 数组；部分失败不影响其他条目。

{ "batch": [
  { "type": "identify", "userId": "u_123", "messageId": "…" },
  { "type": "track", "userId": "u_123", "event": "Logged In", "messageId": "…" }
] }

订阅表单提交（公开）

POST /api/forms/{publicId}/submit 无需密钥，用于您网站上的自有表单直接提交；请求来源必须在表单设置的「允许嵌入的网站」中。开启双重确认时返回 check_email。