Guide

无需 IMAP 为应用添加邮件同步

构建邮件同步通常意味着为每个邮箱维护一个持久的 IMAP IDLE 连接，处理 OAuth 刷新，并在大规模场景下处理重连。本指南展示替代模式：用 Webhook 接收新邮件，用按需读取回填历史，并从终端完成整个原型。

Written by Caleb Geene Director, Site Reliability Engineering

Reviewed by Qasim Muhammad

Verified — CLI 3.1.17 · Gmail, Outlook, IMAP · last tested June 9, 2026

为什么构建 IMAP 同步基础设施很难？

IMAP 同步很难，因为实时投递需要为每一个邮箱保持一条持久的 IDLE 连接。根据 RFC 2177，客户端必须至少每 29 分钟重新发出 IDLE，否则服务器可能断开连接。因此 10,000 个用户意味着 10,000 条长连接，你需要保活、重连，并在进程之间重新均衡。

在这些 socket 之上，还要处理每个账户的 OAuth token 刷新、XOAUTH2 认证、各 provider 的差异，以及节点重启时成千上万邮箱同时重新握手造成的重连风暴。 在解析第一封邮件前，你已经要投入数周基础设施工作 — 真正半夜 3 点叫醒你的也是这部分， 不是你原本想做的功能。

什么可以替代 IMAP 同步？

替代方案是 push-plus-pull 模式：新邮件到达时，webhook 发送一个小通知； 只有当应用需要内容时，才按需读取这封邮件。你不需要保持任何持久连接。 Provider 告诉你发生了变化，你只取那一项。这也是 Gmail 和 Microsoft Graph 推送模型底层的工作方式。

这会反转成本结构。你不再为保持成千上万条空闲 socket 付费，而是为每封新邮件支付一次廉价的 webhook 通知，再加上实际使用的读取。一个每天收到 50 封邮件的邮箱，成本是 50 次通知， 不是 24 小时保持连接。

如何在没有 IMAP 的情况下原型化邮件同步？

你可以用两个终端命令原型化整个模式。注册一个 message.created webhook，让你的 endpoint 在每封新邮件到达时收到通知，然后运行内置 receiver 观察 payload 到达。无需 server framework，无需 socket pool — 你会看到应用需要处理的真实 push 形状。

# 1. Push new mail to your endpoint
nylas webhook create \
  --url https://your-app.example.com/inbound \
  --triggers message.created \
  --description "email sync"

# 2. Watch payloads locally while you build the handler
nylas webhook server --port 9000

收到通知后，按需获取邮件正文。 nylas email read 命令接收 webhook 中的 message ID，并以 JSON 返回完整内容 — 这是你唯一需要的读取，而且只在需要时发生。

# In your handler: fetch just the message the webhook pointed at
nylas email read "$MESSAGE_ID" --json | jq '{from: .from, subject: .subject}'

如何回填已有邮件？

回填历史时使用按需搜索，而不是完整同步。 nylas email search 命令直接查询邮箱， --after 日期过滤器把导入范围限制在最近窗口，这样你不会拉取多年用不到的邮件。大多数应用在 onboarding 时只需要最近 30–90 天。

# One-time backfill of the last 30 days at user onboarding
nylas email search "*" --after 2026-05-10 --json > backfill.json
jq 'length' backfill.json

什么时候仍然需要 IMAP？

当邮箱没有现代 API 时，你仍然需要 IMAP — 例如自托管 Dovecot 服务器、旧主机， 或只暴露 IMAP 的小众 provider。在这些场景中没有 webhook 可订阅，所以 polling 或 IDLE client 无法避免。真实的取舍是：push 模型需要支持通知的 provider。

即便如此，CLI 也通过同一套命令界面连接通用 IMAP 账户，所以你无需自己编写 IMAP client， 仍能获得统一读取模型。大多数团队会发现无 IMAP 路径覆盖 Gmail、Outlook 和主要 provider — 也就是大部分真实用户 — 然后只为长尾保留 polling fallback。

下一步