Immich 邮件通知配置实战：使用 Microsoft 365 / Outlook 应用密码接入 SMTP

Immich 支持通过 SMTP 发送欢迎邮件、共享相册邀请与更新通知等系统邮件，而使用 Microsoft 365 / Outlook 账号作为发信通道是最常见的自建场景之一。本文基于仓库中的 SMTP Microsoft 365 配置指南 展开，完整覆盖应用密码创建、Immich 管理后台 SMTP 参数填写，并结合后端源码讲清 Immich 是如何解析、校验并最终发出这些邮件的，读完你可以独立完成一套可验证、可排错的 Immich 邮件通知配置。

一、Immich 中 SMTP 的作用与邮件触发链路

在 Immich 中，SMTP 配置位于系统级设置，服务于以下邮件场景（对应后端 EmailRepository 中定义的 EmailTemplate 枚举）：

• 测试邮件（test）：管理员在设置页一键验证 SMTP 配置是否可用；
• 欢迎邮件（welcome）：管理员为用户创建账号并开启通知时发送；
• 相册邀请（album-invite）：他人把你加入共享相册时发送，可携带相册缩略图附件；
• 相册更新（album-update）：共享相册新增媒体时发送，同样可携带缩略图。

从源码结构看，邮件并不在请求线程中同步发出：各业务事件（UserSignup、AlbumInvite、AlbumUpdate 等）先投递到 Notification 队列，最终由 SendMail 任务统一读取当前 SMTP 配置并调用 emailRepository.sendEmail 发送，完整实现见 NotificationService。因此只要队列中 SMTP 配置被禁用（notifications.smtp.enabled 为 false），发送任务会被直接跳过（返回 JobStatus.Skipped）。

二、第一步：创建 Microsoft 应用密码

直接使用 Microsoft 邮箱的主账号密码登录 SMTP 服务器通常会被拒绝，需要为账号生成一个应用密码（App Password），供 Immich 作为 SMTP 认证密码使用。根据账号类型，入口不同：

• 个人账号（Outlook.com / Hotmail 等）：登录 Microsoft 账号的“安全信息”（Security info）页面，在其中创建新的应用密码；
• 工作 / 学校（Microsoft 365）账号：通过 Microsoft 提供的 2SV 应用密码管理入口创建。

应用密码生成后请立即妥善保存，它只会显示一次，之后将填入 Immich 的 SMTP 密码字段。

三、第二步：在 Immich 中填写 SMTP 凭据

进入管理后台路径：Administration -> Settings -> Notification Settings（该页面对应前端文件 NotificationSettings.svelte），按下表填写 Microsoft 通道的参数：

参数	取值	说明
Host（主机）	smtp-mail.outlook.com	Microsoft 的 SMTP 服务器地址
Port（端口）	587	对应 Immich 配置中的默认端口值
Username（用户名）	你的 Microsoft 邮箱地址	用于 SMTP 认证
Password（密码）	第二步创建的应用密码	不是邮箱登录密码
SMTPS	禁用（disabled）	587 端口走 STARTTLS 升级加密，而非 465 的隐式 TLS

“SMTPS 禁用”在源码中意味着什么

Immich 后端把界面中的 SMTPS 开关映射为 nodemailer 的 secure 选项。见 SmtpOptions 类型定义 与 createTransport 实现：

private createTransport(options: SmtpOptions) {
  return createTransport({
    host: options.host,
    port: options.port,
    tls: { rejectUnauthorized: !options.ignoreCert },
    secure: options.secure,
    auth:
      options.username || options.password
        ? { user: options.username, pass: options.password }
        : undefined,
    connectionTimeout: 5000,
  });
}

• secure: false（即界面中 SMTPS 关闭）+ 端口 587：连接建立后通过 STARTTLS 升级为加密通道，这正是 Outlook SMTP 587 端口的标准用法；若你把端口改到 465，则需要将 SMTPS 打开（secure: true，隐式 TLS）；
• ignoreCert 对应 tls.rejectUnauthorized，默认关闭证书跳过；只有在企业内网使用自签名证书等特殊场景才需要打开；
• connectionTimeout: 5000：连接超时固定为 5 秒，超时即判定配置不可用。

系统配置的默认值同样印证了上述约定，见 config.dto.ts 中 notifications.smtp 默认项：enabled: false、port: 587、secure: false、ignoreCert: false。

四、配置校验与测试邮件的验证机制

填写完成后不要跳过验证，Immich 提供了两层校验：

1. 配置保存时自动验证：NotificationService 注册了 ConfigValidate 事件钩子，只要 SMTP 处于启用状态且配置发生变化，就会调用 emailRepository.verifySmtp（底层为 nodemailer 的 transport.verify()，建立一次握手后即关闭连接）；失败会抛出 “Invalid SMTP configuration” 并记录 Failed to validate SMTP configuration 日志，见 onConfigValidate 实现。
2. 手动发送测试邮件：Send Test Email 按钮走 sendTestEmail 流程——先 verifySmtp 验证连通性与认证，再渲染 test.email 模板（位于 emails 目录），以 from 发件人、replyTo 回复地址发往当前登录管理员邮箱；验证不通过会返回 “Failed to verify SMTP configuration”。

测试邮件中的链接域名取决于系统设置里的外部域名（server.externalDomain），由 getExternalDomain 计算注入模板，因此如果你的部署有公网访问地址，建议一并配置以保证邮件内链接可点击。

五、可自定义的邮件模板

Notification Settings 之外的 Template Settings 页面（Administration -> Settings -> Template Settings）允许管理员为 welcomeTemplate、albumInviteTemplate、albumUpdateTemplate 配置自定义 HTML 模板（默认值定义见 config.dto.ts templates.email）。模板为可选增强项：不配置时使用内置的 React Email 模板（emails 目录 下的 .email.tsx 组件），它们同时渲染 HTML 与纯文本两种版本，由 renderEmail 统一产出。

六、排错要点

结合源码行为，Microsoft 通道常见的失败点与排查方向如下：

• 认证失败：绝大多数是密码填了主密码而非应用密码，或应用密码已被撤销；确认使用第二步生成的一次性密码；
• 端口 / 加密方式不匹配：587 端口必须保持 SMTPS 关闭（STARTTLS）；如果运维侧只放行了 465 端口，则应改用 465 并打开 SMTPS；
• 证书校验失败：仅当出现自签名证书链问题时才考虑打开 ignoreCert，正常 Microsoft 公网证书无需开启；
• 保存配置即报错：由于 ConfigValidate 钩子会实时 verifySmtp，保存失败通常等价于“测试邮件必失败”，优先按上述顺序检查主机、端口、认证三要素；
• 发送状态确认：每次任务发送成功后会记录 Sent mail with id: <messageId> 日志，可用其确认邮件是否真正投递。

单元测试与中测分别覆盖上述行为，可参考 email.repository.spec.ts 与 notification.service.spec.ts。

小结

使用 Microsoft 365 / Outlook 接入 Immich 邮件通知的核心步骤只有两步：为 Microsoft 账号创建应用密码，然后在 Administration -> Settings -> Notification Settings 中按 smtp-mail.outlook.com:587 + 邮箱地址 + 应用密码 + SMTPS 关闭的参数填写，并用 Send Test Email 验证。理解后端将其映射为 nodemailer secure: false（STARTTLS）的传输参数后，你就能自行推导出 465 端口、自签名证书等变体场景下的正确配置，而不是只依赖固定参数表。如果你使用 Gmail 通道，可参考仓库中同系列的 Gmail SMTP 配置指南。