react-native-email-imap-smtp

React Native IMAP & SMTP 邮件客户端库，基于 Nitro Modules 构建。

平台支持

| 平台 | 状态 | 实现 | |------|------|------| | Android | ✅ 可用 | Kotlin + Jakarta Mail | | Web | ✅ 可用 | HTTP Proxy（imapflow + nodemailer），查看详情 | | iOS | ⚠️ 开发中 | 尚未完成 | | Windows | ❌ 暂停 | 计划后续重写 |

安装

npm install react-native-email-imap-smtp

Android 用户：还需额外安装 react-native-nitro-modules，因为 Android 端基于 Nitro Modules 构建。

Web 用户：本库已内置代理服务器，安装主包即可，无需其他依赖。

快速开始

import {
  imapConnect,
  imapSelectMailbox,
  imapFetchEmails,
  smtpConnect,
  smtpSendMail,
} from 'react-native-email-imap-smtp';

// 1. 连接 IMAP 服务器
const conn = await imapConnect({
  host: 'imap.163.com',
  port: 993,
  username: '[email protected]',
  password: 'your-authorization-code',
  tls: true,
  checkCertificate: false,
});

// 2. 选择收件箱
const inbox = await imapSelectMailbox('INBOX');

// 3. 获取邮件
const emails = await imapFetchEmails({ fetchBody: true, fetchHeaders: true });

完整示例请查看 example/ 目录。

Web 支持

浏览器没有 TCP Socket 能力，无法直连 IMAP/SMTP 服务器。Web 端通过本地代理服务器转发请求：

┌────────────────┐   HTTP/JSON    ┌────────────────────┐   TCP/TLS    ┌────────────┐
│  浏览器 App    │ ──────────────> │  本地代理服务器     │ ───────────> │  邮件服务器  │
│  (你的代码)     │ <────────────── │  imapflow          │ <─────────── │  IMAP/SMTP  │
└────────────────┘                │  + nodemailer      │             └────────────┘
                                  └────────────────────┘

代理服务器随本库一起发布，安装主包即可使用。

用法一：修改 dev 脚本（推荐）

在 package.json 的 dev 命令前加上 email-imap-proxy &：

{
  "scripts": {
    "dev": "email-imap-proxy & vite",
    "dev": "email-imap-proxy & next dev",
    "dev": "email-imap-proxy & webpack serve"
  }
}

之后 npm run dev 会自动启动代理服务器，与应用并行运行。

原理：email-imap-proxy 是本库提供的 CLI 命令。安装后 npm 会在 node_modules/.bin/ 中创建符号链接，脚本中可直接使用。

用法二：手动启动

# 启动代理（首次自动安装依赖并编译）
npx email-imap-proxy

# 另开终端启动应用
npm run dev

代理自动处理

| 场景 | 行为 | |------|------| | 依赖未安装 | 自动 npm install | | TypeScript 未编译 | 自动 tsc | | 端口被占用 | 检测到已有实例，自动复用 | | 代理未运行 | 首次 API 调用时抛出清晰指引 |

自定义地址

import { setProxyUrl } from 'react-native-email-imap-smtp';
setProxyUrl('http://localhost:8080');

setProxyUrl 是 Web 平台专属，原生平台上为 undefined。

程序化启动

import { startEmailProxy } from 'react-native-email-imap-smtp/server/proxy';
const handle = await startEmailProxy({ port: 3987 });
await handle.stop();

网易邮箱（163/188.com）配置指南

网易邮箱必须使用授权码登录，不允许直接使用登录密码。

获取授权码

1. 登录 mail.163.com 网页版
2. 设置 → POP3/SMTP/IMAP
3. 开启 IMAP/SMTP 服务
4. 点击 新增授权码，完成手机验证
5. 将生成的授权码填入 password 字段

配置参数

{
  host: 'imap.163.com',
  port: 993,
  username: '[email protected]',
  password: '授权码',           // ⚠️ 不是登录密码！
  tls: true,
  checkCertificate: false,     // 网易邮箱需关闭证书校验
  timeout: 30000,
}

常用邮箱服务器

| 邮箱 | IMAP 服务器 | IMAP 端口 | SMTP 服务器 | SMTP 端口 | |------|------------|----------|------------|----------| | 163 | imap.163.com | 993 | smtp.163.com | 465 | | 188 | imap.188.com | 993 | smtp.188.com | 465 | | QQ | imap.qq.com | 993 | smtp.qq.com | 465 | | Gmail | imap.gmail.com | 993 | smtp.gmail.com | 465 |

常见错误

| 错误信息 | 原因 | 解决方法 | |---------|------|---------| | NO SELECT Unsafe Login | 服务器拒绝 SELECT 命令 | 使用授权码，开启 IMAP 服务 | | Connection reset | SSL 证书验证失败 | 设置 checkCertificate: false | | NO Login | 认证失败 | 检查账号和授权码 |

API 文档

详细 API 文档见 docs/IMAP_SMTP_通信实现细节.md。

贡献

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library