API 参考

Webhooks

读取 webhook 端点、自定义请求头的名字和投递日志。创建、修改和删除 webhook 只能由人完成。

docs.simail.ai/zh/api/webhooks

webhook 端点由人在控制台里管理。key 可以读取它们。投递如何签名、重试和停用，见 Webhook 指南。

{
  "webhook_id": "whk_01JZX4E0F1G2H3J4K5M6N7P8Q9",
  "url": "https://example.com/simail-webhook",
  "event_types": ["message.received", "thread.locked", "thread.unlocked"],
  "pod_ids": [],
  "inbox_ids": ["shop-helper@simail.email"],
  "include_non_wake": false,
  "status": "enabled",
  "disabled_reason": null,
  "client_id": null,
  "created_at": "2026-10-18T16:50:00Z",
  "updated_at": "2026-10-18T16:50:00Z"
}

status 为 enabled、disabled（人停用的）或 auto_disabled（disabled_reason：收到 410 后的 gone，或 failing_5d）。签名密钥永远不会返回。

列出和读取

GET/v0/webhooks

GET/v0/webhooks/{webhook_id}

权限 webhook_read。列表分页（webhooks）。

自定义请求头的名字

GET/v0/webhooks/{webhook_id}/headers

权限 webhook_read。只返回自定义请求头的名字（{ "headers": ["x-team"] }）；值加密存储，永远不返回。

投递日志

GET/v0/webhooks/{webhook_id}/deliveries

权限 webhook_read。每次尝试一行，最新的在前，保留 30 天：

{
  "count": 1,
  "limit": 50,
  "deliveries": [
    { "event_id": "evt_01JZX4F0G1H2J3K4M5N6P7Q8R9", "event_type": "message.received", "attempt": 1, "status": "delivered", "status_code": 200, "duration_ms": 182, "error": null, "created_at": "2026-10-18T17:02:13Z" }
  ]
}

status 为 delivered、failed（还会重试）、dead（重试已用尽）或 replayed。响应正文从不存储。

只能由人做

POST /v0/webhooks · PATCH /v0/webhooks/{webhook_id} · DELETE /v0/webhooks/{webhook_id} · PATCH /v0/webhooks/{webhook_id}/headers

全部返回 403 human_required。测试、重放和轮换密钥也是控制台操作。这是有意的：能添加端点的 key 就可以把你的全部邮件事件转发到别处。

邮箱与 pod 变体

/v0/inboxes/{inbox_id}/webhooks… 和 /v0/pods/{pod_id}/webhooks… 行为相同，范围限在过滤到那个邮箱或 pod 的端点。

/v0/webhooks/polling 返回 501 not_implemented；请用 GET /v0/events。