imapflow

ImapFlow 概述 ImapFlow 是一个现代的、基于 Promise 的 IMAP 客户端，用于 Node.js。它可以自动检测和处理 IMAP 扩展（CONDSTORE、QRESYNC、IDLE、COMPRESS 等），因此相同的代码可以在不同的服务器上运行。主要特性包括：async/await API、异步迭代器用于消息流、内置的邮箱锁定、TypeScript 支持、SOCKS/HTTP 代理支持、Gmail X-GM-EXT-1 支持。

触发场景 在构建电子邮件功能时使用：连接到 IMAP 服务器、获取/阅读电子邮件、搜索邮箱、管理文件夹、通过 IDLE 监控新消息、使用 Gmail 标签和 Gmail 特定扩展，或者任何基于 IMAP 的电子邮件自动化。

快速开始

const { ImapFlow } = require('imapflow');
const client = new ImapFlow({
  host: 'imap.example.com',
  port: 993,
  secure: true,
  auth: {
    user: 'user@example.com',
    pass: 'password'
  }
});
await client.connect();
let lock = await client.getMailboxLock('INBOX');
try {
  // 获取最新消息
  let msg = await client.fetchOne(client.mailbox.exists, { source: true });
  console.log(msg.source.toString());
  // 流式获取所有消息
  for await (let msg of client.fetch('1:', { envelope: true })) {
    console.log(${msg.uid}: ${msg.envelope.subject});
  }
} finally {
  lock.release();
}
await client.logout();

核心任务

• 连接

const client = new ImapFlow({
  host: 'imap.example.com',
  port: 993,
  secure: true,
  auth: {
    user: 'user@example.com',
    pass: 'password'
  }
});
await client.connect();

auth: {
  user: 'user@gmail.com',
  accessToken: 'ya29.xxx...'
}

• 获取消息

let lock = await client.getMailboxLock('INBOX');
try {
  // ... 获取操作 ...
} finally {
  lock.release();
}

let msg = await client.fetchOne('', { source: true });
// 或通过序列号：
client.fetchOne(42, { source: true })
// 或通过 UID（追加 uid 标志）：
let msg = await client.fetchOne('12345', { uid: true, source: true });

流式/迭代消息：

// 范围：序列号
for await (let msg of client.fetch('1:100', { envelope: true, flags: true })) {
  console.log(${msg.seq}: ${msg.envelope.subject});
}
// 所有消息：'1:'
for await (let msg of client.fetch('1:', { envelope: true })) {
  / ... /
}
// 通过 UID 范围
for await (let msg of client.fetch('1000:2000', { uid: true, envelope: true })) {
  / ... /
}

let msg = await client.fetchOne('', { bodyParts: ['1.1', '1.2'], // MIME 部分路径
  source: true });
// msg.bodyParts.get('1.1') → Buffer
// msg.text.toString() → 解码的文本内容

let msg = await client.fetchOne('', { source: true, bodyStructure: true });
for (let attachment of msg.attachments) {
  let buf = await client.download(msg.uid, attachment.part, { uid: true });
  // buf 包含附件数据
}

• 搜索

let lock = await client.getMailboxLock('INBOX');
try {
  // 简单搜索
  let list = await client.search({ unseen: true });
  // 复杂查询
  let list = await client.search({
    from: 'sender@example.com',
    subject: 'invoice',
    seen: false,
    since: new Date('2024-01-01'),
    before: new Date('2024-12-31'),
    larger: 1024 * 1024 // > 1MB
  });
  // 文本搜索（正文）
  let list = await client.search({ body: '重要关键词' });
  // 结合 OR
  let list = await client.search({
    or: [
      { from: 'alice@example.com' },
      { from: 'bob@example.com' }
    ]
  });
  // 结合 AND + OR
  let list = await client.search({
    subject: '报告',
    or: [
      { from: 'alice@example.com' },
      { from: 'bob@example.com' }
    ]
  });