Swanmail

账号 ​

Swanmail 支持多种账号类型。账号数据保存在本地 SQLite 中，凭证用保存在 macOS 钥匙串、由 Windows DPAPI 保护或保存在 Linux Secret Service 中的密钥加密（见隐私）。

OAuth 凭证 ​

Gmail 和 Outlook / Microsoft 365 使用 OAuth 2.0。登录页面在你的浏览器中打开，完成后通过本机地址回到 Swanmail。

内置客户端。 发布版本自带 Google 和 Microsoft 客户端，因此 使用 Google 登录 和 使用 Microsoft 登录 无需任何配置即可使用——Microsoft 个人账户（Outlook.com、Hotmail、Live）和工作或学校账户都可以。Yahoo 和 Fastmail 没有 OAuth 登录：请使用应用专用密码或 API token 添加这些账户。

覆盖。 高级用户和开发者可以在运行时通过以下两种方式之一替换内置客户端：

  1. Swanmail 数据目录中的 config.json 文件。
  2. 启动 Swanmail 的环境中的环境变量：SWANMAIL_GMAIL_CLIENT_ID、SWANMAIL_GMAIL_CLIENT_SECRET、SWANMAIL_OUTLOOK_CLIENT_ID、SWANMAIL_OUTLOOK_TENANT_ID。

每个值依次查找 config.json、环境变量、内置值。Microsoft 租户默认为 common。

只有配置了客户端的服务商才会出现登录按钮：使用 Google 登录 需要同时有 client ID 和 secret，使用 Microsoft 登录 需要 client ID。没有配置时按钮只会失败，所以对话框会直接显示手动添加表单。

目前应用中没有输入 OAuth 凭证的表单。这是有意为之：注册 OAuth 应用、复制 client ID 是高级/开发者任务，把它暴露在主界面里只会让想直接登录的用户感到困惑。

config.json ​

在 Swanmail 的数据目录中创建或编辑 config.json：

  • macOS：~/Library/Application Support/swanmail/config.json
  • Windows：%APPDATA%\swanmail\config.json
  • Linux：~/.config/swanmail/config.json（或在 $XDG_CONFIG_HOME 下）

环境变量 SWANMAIL_DATA 可以改变整个目录。

示例：

json
{
  "gmailClientId": "your-gmail-client-id",
  "gmailClientSecret": "your-gmail-client-secret",
  "outlookClientId": "your-outlook-client-id",
  "outlookTenantId": "common"
}

编辑后重启应用即可生效。

本地开发 ​

从源码构建时，内置的 Google 和 Microsoft 客户端取自项目根目录下被 git 忽略的 .env.local：

bash
SWANMAIL_GMAIL_CLIENT_ID=your-gmail-client-id
SWANMAIL_GMAIL_CLIENT_SECRET=your-gmail-client-secret
SWANMAIL_OUTLOOK_CLIENT_ID=your-outlook-client-id

pnpm dev 运行后端时不经过读取该文件的构建步骤，所以使用 pnpm dev 时，请在运行它的 shell 中导出这些变量，或写入开发配置目录（.dev-profile/）中的 config.json。

Gmail ​

发布版本可以直接登录 Gmail：在 设置 → 账户 → 添加账户 中选择 使用 Google 登录 即可。如果要改用你自己的 Google 客户端：

  1. 在 Google Cloud Console 创建项目。
  2. 启用 Gmail API。
  3. 创建类型为 桌面应用 的 OAuth 2.0 凭据。
  4. 按上面的示例把 client ID 和 secret 写入 config.json（gmailClientId、gmailClientSecret）。
  5. 在 Swanmail 中前往 设置 → 账户 → 添加账户，选择 使用 Google 登录，完成登录流程。

Outlook / Microsoft 365 ​

发布版本可以直接登录 Microsoft，个人账户（Outlook.com、Hotmail、Live）和工作或学校账户都一样：在 设置 → 账户 → 添加账户 中选择 使用 Microsoft 登录 即可。你所在的组织仍可能要求管理员批准该应用。如果要改用你自己的应用注册：

  1. 在 Microsoft Entra 管理中心 → 应用注册 中注册应用，支持的账户类型选择任何组织目录中的账户和个人 Microsoft 账户。
  2. 添加类型为 公共客户端/本机（移动和桌面） 的重定向 URI：http://localhost。Swanmail 在随机端口上接收回调，端口不参与匹配。没有 client secret。在 身份验证 中，把 允许公共客户端流 设为“是”。
  3. 添加以下委托 API 权限：offline_access、openid、email、profile、User.Read，以及 Office 365 Exchange Online 的 IMAP.AccessAsUser.All 和 SMTP.Send。Microsoft Graph 账户还要添加 Microsoft Graph 的 Mail.ReadWrite、Mail.Send、Mail.ReadWrite.Shared、Mail.Send.Shared 和 MailboxSettings.Read。
  4. 把 client ID 写入 config.json（outlookClientId）；tenant ID 不是 common 时再写入 outlookTenantId。
  5. 在 Swanmail 中前往 设置 → 账户 → 添加账户，选择 使用 Microsoft 登录，完成登录流程。

Yahoo ​

Yahoo 的邮件权限（mail-r、mail-w）不对开发者自助开放：应用需要向 Yahoo 提交申请并通过审核， 才能通过 OAuth 读取邮件。给自己的账户用，请使用应用专用密码：

  1. 在 Yahoo 中前往 Account Info → Account security → Generate app password。
  2. 在 Swanmail 中前往 设置 → 账户 → 添加账户，填入 Yahoo 邮箱地址和应用专用密码， 服务器地址会自动填好。

Swanmail 没有 Yahoo 的 OAuth 登录。

Fastmail ​

Fastmail 不提供自助注册 OAuth 应用的入口，Swanmail 也没有 Fastmail 的 OAuth 登录。 可以手动添加账户，填 API token 或应用专用密码：API token 走 JMAP 同步和发信， 应用专用密码走 IMAP 和 SMTP。Fastmail 的 JMAP 接口只接受 Bearer 令牌，不接受密码。

使用 API token（JMAP，个人使用推荐） ​

  1. 在 Fastmail 中前往 设置 → Privacy & Security → Manage API tokens，新建一个 token。 勾选 Email 权限，要发信还需勾选 Email submission；不要设为只读。token 只显示一次， 记得复制下来。它以 fmu1- 开头。
  2. 在 Swanmail 中前往 设置 → 账户 → 添加账户，选择 或手动添加，填入 Fastmail 邮箱地址，把 token 粘贴到 密码 栏。无论是 Fastmail 的哪个域名，还是托管在 Fastmail 上的自有域名，服务器地址都会自动填好。
  3. Swanmail 会识别出这是 token，用 Bearer 方式登录 JMAP，账户通过 JMAP 同步和发信， 并显示 JMAP 徽标。如果 Fastmail 拒绝这个 token，添加账户时会直接提示。

token 只能用于 JMAP。如果没有勾选 Email submission，发信会退回 SMTP，而 token 无法登录 SMTP，发信就会失败。

使用应用专用密码（IMAP 和 SMTP） ​

  1. 在 Fastmail 中前往 设置 → Privacy & Security → Manage app passwords and access， 新建一个带邮件访问权限（IMAP、SMTP）的应用专用密码。
  2. 在 Swanmail 中前往 设置 → 账户 → 添加账户，选择 或手动添加，填入 Fastmail 邮箱地址和刚才的应用专用密码。服务器地址会自动填好（imap.fastmail.com、 smtp.fastmail.com）。
  3. 账户通过 IMAP 同步、通过 SMTP 发信。Swanmail 会先用这个密码尝试 JMAP，Fastmail 会拒绝， 于是账户留在 IMAP 上，其他一切照常。

要用 JMAP，请改用上面的 API token。

QQ 邮箱、腾讯企业邮和网易邮箱 ​

QQ 邮箱（qq.com、foxmail.com）和网易邮箱（163.com、126.com、yeah.net）用 授权码 登录，不是网页版的登录密码，也不为其他应用提供 OAuth 登录：

  1. 在网页版邮箱的设置中开启 IMAP/SMTP 服务，并生成授权码。QQ 邮箱在 设置 → 账号，网易邮箱在 设置 → POP3/SMTP/IMAP。
  2. 在 Swanmail 中打开 设置 → 账户 → 添加账户，输入邮箱地址，把授权码粘贴到 密码 栏。服务器会自动填好。

腾讯企业邮（imap.exmail.qq.com）和网易企业邮（imap.qiye.163.com）会根据你的公司域名自动识别。腾讯企业邮填邮箱密码；如果开启了安全登录，填客户端专用密码。

几点说明：

  • 网易邮箱不为没有自报身份的客户端打开邮箱，所以 Swanmail 登录后会向支持的服务器发送 IMAP ID 命令。
  • 网易邮箱的文件夹用中文命名（已发送、草稿箱、已删除、垃圾邮件），Swanmail 会把它们识别为已发送、草稿、废纸篓和垃圾邮件。
  • QQ 邮箱可以自己保存通过 SMTP 发出的邮件。Swanmail 在保存自己的副本前会先检查有没有这份副本，所以已发送里不会出现两封。Outlook 和 Gmail 也是这样。
  • 你在 QQ 邮箱里自建的文件夹，要在 QQ 邮箱的 IMAP 设置中允许收取后，才会通过 IMAP 显示。

通用 IMAP/SMTP ​

在 添加账户 对话框中，点击快捷登录按钮下方的 或手动添加，即可连接任何暴露标准 IMAP 和 SMTP 端点的邮件服务商。

离开邮箱地址栏时，Swanmail 会为 Google、Microsoft、Yahoo、iCloud 和 Fastmail 的地址自动填好服务器， 托管在这些服务商上的自有域名也一样：它通过查询域名的 MX 记录判断由谁接收邮件。你手动填写的服务器不会被覆盖。 你需要准备：

  • IMAP 主机和端口
  • SMTP 主机和端口
  • 邮箱地址和密码（或应用专用密码）

POP3 ​

在 添加账户 对话框的手动表单中，把 协议 从 IMAP 切换为 POP3。你需要准备 POP3 主机和端口（TLS 为 995；其他端口会用 STLS 升级），以及用于发信的 SMTP 主机和端口 —— POP3 只能收信。

POP3 是下载协议，不是同步协议：只有一个邮件暂存区，没有文件夹，没有标记，也无法把你对 邮件做的操作告诉服务器。因此 Swanmail 中的 POP3 账户是这样工作的：

  • 只有一个收件箱。 服务器上的邮件都会进入其中，首次同步最多取最新的 200 封。
  • 本地副本就是全部。 邮件下载后保存在 Swanmail 的数据库中，即使服务器上已不存在也仍然保留。
  • 已读状态、星标、文件夹和移动都是本地的。 它们真实有效并会保存，但只存在于 Swanmail 中， 其他客户端和网页邮箱都看不到，也没有可同步回去的地方。
  • 删除邮件删除的是你的副本，不是服务器上的副本。
  • 没有服务端搜索。 搜索 POP3 账户即搜索已下载的内容，而那就是它的全部。
  • 新邮件靠轮询获取，每 30 秒一次，因为 POP3 既没有 IDLE 也没有推送通道。

下载后从服务器删除 ​

添加账户表单会为 POP3 账户提供 下载后从服务器删除 选项，默认关闭，即所有邮件都保留在 服务器上。

启用后，Swanmail 每存好一封邮件就会将其从服务器删除；删除在会话结束时才提交，因此中断的同步 不会删除任何邮件。如果邮箱较小、且没有其他客户端在用，这个选项很合适；但如果你同时在手机上收 同一个账户，就不要开启：哪个客户端先下载，邮件就只留在哪一边。该设置随账户保存在 Swanmail 的 数据库中。

通过 Graph 连接 Microsoft 365 ​

许多组织在其 Microsoft 365 租户上关闭了 IMAP。使用 Microsoft 登录 走 IMAP，并在添加账户前 先用它试一次 IMAP 登录。如果邮箱拒绝，Swanmail 不会添加账户，而是显示服务器给出的原因，并提供 改用 Microsoft Graph 连接：之后 Swanmail 通过 Microsoft 自己的 API 访问邮箱，而它无法被租户单独关闭。 此外，Microsoft 将从 2026 年 10 月 1 日起停止第三方应用通过 EWS 访问 Exchange Online， 因此对工作或学校邮箱来说，Graph 是长期可行的方式。

Graph 需要不同的权限，所以选择它会再打开一次 Microsoft 登录页面，请求你授权。

它会请求哪些权限 ​

通过 Graph 连接时，会请求你的 Microsoft 账户批准：

  • 读写你的邮件 —— Swanmail 需要标记已读、加星标、移动邮件和创建文件夹。
  • 以你的身份发信。
  • 读写与你共享的邮箱中的邮件，并从这些邮箱发信 —— 只用于你添加的共享邮箱。
  • 读取你的邮箱设置 —— 只用于获取 Outlook 类别的颜色。
  • 读取你的基本资料 —— 用于确认你刚刚登录的是哪个地址。
  • 保持登录状态，这样不必每次重新授权。

选择 IMAP 则与以往完全一致，不会多请求任何权限。无论选哪一种，你所在的组织都可能要求管理员 批准。

在创建账户之前，Swanmail 会先确认确实能读取你的文件夹。如果登录成功但邮箱仍然无法访问——没有 Exchange 许可证，或有策略拦截了该应用——错误会直接出现在按钮上，而不是留给你一个永远同步 不了的账户。

与 IMAP 的区别 ​

几乎所有功能都一样：文件夹、已读状态、星标、移动、删除、清空回收站、创建和重命名文件夹、 搜索以及发信都可用，并且都会同步到服务器。

有四点差异值得了解：

  • 新邮件按定时检查，而不是推送：你在使用电脑时每 5 秒一次，键盘和鼠标闲置五分钟后改为每 30 秒一次。Graph 提供的推送机制需要一个公网地址来 接收通知，而运行在你自己电脑上的应用没有这样的地址。
  • 已发送副本由 Exchange 归档，而不是由 Swanmail 写入，因此你发出的邮件会在下次同步时 出现在“已发送”中，而不是立即出现。
  • 不显示邮件大小，因为 Graph 不提供该信息。
  • 单封邮件连同附件最多约 3 MB。 这是 Graph 发送完整邮件的接口上限，而 Graph 账户没有 SMTP 可以回退。超出时 Swanmail 会在发送前提示，不会发出任何内容。

已有的 Microsoft 账户仍保持 IMAP。没有任何机制会自动更换账户的协议——若要切换，请移除该账户 并重新添加、并选择 Graph，本地邮件会重新下载。

Exchange Server（EWS） ​

如果邮箱位于 自建 Exchange 服务器（Exchange 2013 及以后）且 IMAP 已关闭，请在手动添加账户的表单里把协议选为 Exchange (EWS)。邮件、文件夹、已读状态、星标、移动、搜索和发信全部通过 Exchange Web Services 完成，这也是 Outlook 自己使用的接口。

Microsoft 365 或 Outlook.com 邮箱不要使用它：微软自 2026 年 10 月 1 日起禁止第三方应用通过 EWS 访问 Exchange Online。请改用 Microsoft 按钮，通过 Microsoft Graph 连接。

表单需要填写的内容比 IMAP 账户少：

  • 邮箱地址和密码。 服务器支持时使用 NTLM 登录，否则使用 Basic 认证。只提供 Kerberos（“Negotiate”）的服务器目前无法使用；请管理员在 EWS 上启用 NTLM 或 Basic。
  • 服务器地址——可选。留空时 Swanmail 会根据你的地址通过 Autodiscover 自动查找。如果找不到，请手动填写，通常形如 https://mail.example.com/EWS/Exchange.asmx。
  • 登录名——可选。很多服务器要求使用 DOMAIN\user 或用户主体名称，而不是邮箱地址。
  • 接受非公共机构签发的证书——用于使用内部证书颁发机构的服务器。只应在你信任的网络上对你信任的服务器勾选。

表单里没有 IMAP 和 SMTP 字段：发信走同一个 Exchange 端点，已发送副本由 Exchange 自己归档。

与 IMAP 相比值得了解的差异：

  • 新邮件按定时检查，而不是推送：你在使用电脑时每 10 秒一次，闲置五分钟后改为每 30 秒一次。
  • 服务器搜索只覆盖主要文件夹（收件箱、已发送、归档、草稿等几个），不会遍历超大邮箱的每个文件夹。本地搜索覆盖所有已下载的邮件。
  • 该协议是依据微软的规范和测试向量实现的，尚未在大量真实服务器上验证。如果登录或同步失败，错误信息里会带有 Exchange 的响应码，反馈问题时请一并附上。

Exchange 附加功能 ​

除非段落里另有说明，以下内容同时适用于通过 Graph 连接的 Microsoft 365 账户和 Exchange Server（EWS） 账户。

共享邮箱 ​

如果组织给了你访问另一个邮箱的权限——例如 support@ 这样的团队收件箱，或你代为管理的同事邮箱——可以在 设置 → 账户 → 编辑 → 共享邮箱 中填写它的地址和想显示的名称。下次同步后，它的文件夹会以该名称作为独立分组显示在侧边栏中你自己的文件夹下方。阅读、标为已读、加星标、在它的文件夹之间移动、删除（进入它自己的“已删除邮件”）和服务器搜索都与你自己的邮箱一样可用。邮件不能从共享邮箱移到你自己的文件夹，反之亦然：Exchange 把它们视为两个独立的邮箱。

Swanmail 使用管理员授予的权限（完全访问，或对单个文件夹的权限），从不要求服务器模拟任何人。没有访问权限的邮箱会被跳过，账户的其余部分照常同步。从列表中移除共享邮箱会同时移除它的文件夹和从中下载的邮件。

在 Microsoft 365 上，这需要“打开其他邮箱”的权限，Swanmail 在添加 Graph 账户时会请求它。用早期版本添加的账户从未授予该权限：如果共享邮箱的文件夹没有出现，请移除账户后重新添加，或请管理员为整个组织批准该应用的 Mail.ReadWrite.Shared 和 Mail.Send.Shared 权限。

从共享邮箱发信 ​

你添加的每个共享邮箱都会出现在写信窗口的 From 选择器中。选择它即以该邮箱的身份发信，这需要对它拥有 代理发送（Send As） 权限；已发送副本保存在你自己的“已发送邮件”中。

如需更多控制，可再把该地址添加为别名（见下文）并勾选 其他邮箱，随后会出现两个选项：

  • 代表发送 —— 适用于 代表发送（Send on Behalf） 权限。收件人看到的是“你 代表 该邮箱”。
  • 把已发送副本保存在该邮箱中 —— 副本进入共享邮箱自己的“已发送邮件”，团队其他成员都能看到，而不是进入你的邮箱。

如果 Exchange 拒绝——你没有这两种权限，或只有另一种——错误信息会指出是哪个邮箱、缺少哪种权限，邮件不会发出。

公用文件夹 ​

仅限 Exchange Server（EWS）。 完整同步后，服务器的公用文件夹会显示在侧边栏的 Public Folders 下，最多 500 个。每个文件夹显示最新的 50 封邮件或帖子，向下滚动会加载更早的内容。公用文件夹在 Swanmail 中是只读的：可以阅读、标为已读或未读、加旗标，但不能移动、删除或重新整理，应用会直接提示而不是尝试执行。

Microsoft Graph 无法访问公用文件夹，因此通过 Graph 连接的 Microsoft 365 账户不会显示它们；账户设置中也会说明这一点。

类别与标签 ​

在这些账户上，Outlook 类别与 Swanmail 标签是同一回事。下次同步后，邮件的类别会显示为标签——没有对应标签的类别会新建一个，在 Microsoft 365 上颜色与 Outlook 中的类别一致（Exchange Server 不提供类别颜色，因此使用默认颜色）——在 Outlook 中移除类别也会移除该标签。在 Swanmail 中给这类邮件添加或移除标签，会同步设置服务器上的类别，Outlook 中也能看到变化。

名称匹配不区分大小写。有几点只在一侧生效：

  • 在 Swanmail 中重命名、改色或删除标签，不会重命名或删除 Outlook 主类别列表中的类别。
  • 通过命令行工具设置的标签会一直保留在本地，直到在应用中再次修改该邮件的标签。
  • IMAP、JMAP 和 POP3 账户上的标签一如既往，不会离开你的电脑。

发件别名 ​

一个账户可以用不止一个地址发信。在 设置 → 账户 中打开该账户的别名列表，为你的服务商已经允许你使用的每个身份添加名称和地址——Gmail 的“用这个地址发送邮件”、自有域名的 catch-all、Fastmail 别名。写信窗口的 From 选择器随后会列出它们，回复发给某个别名的邮件时会自动选中该别名。Swanmail 拒绝用既不是账户自身地址、也不是其别名的地址发信；它不会向服务商验证别名，服务商可能改写或拒绝它不认识的 From。

JMAP ​

服务商提供 JMAP 的账户（目前对 Fastmail 自动检测）会用 JMAP 而不是 IMAP 同步，并在 设置 → 账户 中显示 JMAP 徽标。这类账户也通过 JMAP 发信：邮件用 EmailSubmission 提交，由服务器归档到已发送；服务器不提供提交能力时回退到 SMTP。在 Fastmail 上，用 Bearer 令牌登录的账户才能用 JMAP：OAuth，或者把 API token 当作密码填入。它的 JMAP 接口不接受其他凭据，所以用应用专用密码添加的账户会留在 IMAP 上。

多账号 ​

每个账号会在侧边栏显示为独立区域。点击账号的邮箱地址会打开它的收件箱，点击右侧箭头可以折叠。按住账号标题直到出现拖动手柄，即可把它拖到其他账号的上方或下方，设置 → 账户 中的列表也按同样的顺序排列。账号和文件夹都可以折叠，重启后侧边栏会保持你离开时的展开状态。每个账号的顶层文件夹可以分别重排序，也可以设置独立的显示标签。

在 设置 → 账户 中，点击账户即可编辑。它的 … 菜单里有签名、文件夹标签、AI 智能体和 移除账户…。移除前会先确认：此设备上该账户的邮件会被删除，包括导入的邮件；服务器上的邮件不受影响。