轮询事件

GET /v0/events 是对邮件做出反应的最简单办法：没有公网 URL，不用验签名，agent 离线时也不会漏（事件保留 30 天）。它返回的薄载荷与 webhook 和 WebSocket 相同；见事件类型。

GET/v0/events

需要 event_read。结果限于 key 的作用域：邮箱作用域的 key 只看得到自己邮箱的事件。

查询参数	说明
after	上一页响应里的游标；第一次调用省略它，从仍保留的最早事件开始
types	逗号分隔的事件类型，例如 message.received,thread.locked
inbox_ids	逗号分隔的、在你作用域内的邮箱 ID
limit	1–200，默认 50

curl -s "https://api.simail.ai/v0/events?types=message.received&limit=100" \
  -H "Authorization: Bearer $SIMAIL_API_KEY"

{
  "count": 1,
  "limit": 100,
  "events": [
    { "event_id": "evt_…", "event_type": "message.received", "occurred_at": "2026-10-18T17:02:12Z", "organization_id": "org_…", "inbox_id": "shop-helper@simail.email", "thread_id": "thr_…", "message_id": "msg_…", "data": { "from": "ada@example.com", "labels": ["received", "unread"], "held": false, "classification": "normal", "wake": true } }
  ],
  "next_cursor": "c_…"
}

记下 next_cursor，下次当作 after 传入。事件按记录顺序给出。轮询返回每一条事件，包括没有唤醒 agent 的（data.wake: false）；如果只要会唤醒的，自己过滤。

游标

• 游标不透明且有签名。它绑定你的组织、key 的作用域和你用过的过滤条件；换一把 key 或其他过滤条件会返回 400 invalid_request。
• 事件保留 30 天。比这更老的游标返回 410 gone：去掉 after 重新开始，并用列出线程来对账。
• 投递至少一次。按 event_id 去重。

轮询循环

let cursor: string | undefined = await loadCursor();
for (;;) {
  const url = new URL("https://api.simail.ai/v0/events");
  url.searchParams.set("types", "message.received,thread.locked,thread.unlocked");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("after", cursor);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.SIMAIL_API_KEY}` } });
  if (res.status === 429) { await sleep(Number(res.headers.get("retry-after") ?? 5) * 1000); continue; }
  const page = await res.json();
  for (const event of page.events) await handle(event); // idempotent on event.event_id
  if (page.next_cursor) { cursor = page.next_cursor; await saveCursor(cursor); }
  if (page.count < 100) await sleep(5000);
}

先处理事件再保存游标，这样崩溃会重放事件，而不是丢掉它们。

单个邮箱的事件

GET/v0/inboxes/{inbox_id}/events

列出一个邮箱的事件，参数相同（没有 inbox_ids）。需要 event_read。

MCP 工具 list_events 接受同样的 after、types、inbox_ids 和 limit。