腾讯企业邮箱
完整配置指南

1. 管理员与成员，两侧分别确认

1.1 管理员：把成员加入协议服务范围

1. 由有邮件管理权限的管理员登录企业微信管理端。
2. 在相应版本的后台进入 协作 → 邮件 → 安全管理 → 客户端访问权限。
3. 查看 IMAP/SMTP 或 POP/SMTP 的服务范围，确认 server@sparrowzoo.com 对应成员或其所在组织在范围内。
4. 保存配置，检查是否同时存在客户端类型、IP 或账号状态方面的限制。

1.2 成员：启用需要的协议组合

1. 在电脑浏览器登录自己的企业邮箱。
2. 进入 设置 → 收发信设置 → 开启服务。
3. 常规收发勾选 开启 IMAP/SMTP 服务；旧系统要求 POP3 时选择 开启 POP/SMTP 服务。
4. 点击 保存更改，重新进入页面，确认状态已保存。

菜单会随邮箱版本、管理入口及企业策略变化。上述为常见路径；找不到入口时，由管理员在当前后台搜索“客户端访问权限”或“协议服务”。开关灰色或无法保存，优先核对管理员服务范围和当前账号状态，不能仅凭界面现象断定唯一原因。

只需要程序发信时，Java 代码只配置 SMTP 即可；后台如果以 IMAP/SMTP 或 POP/SMTP 组合提供开关，仍需按后台实际支持的组合授权。无需为了 SMTP 发信在程序中建立 IMAP 连接。

两侧开关及路径依据：企业微信 · 常用邮件客户端软件 POP/IMAP/EXCHANGE 协议设置。

2. 客户端专用密码：与网页登录密码分清

在启用安全登录的账号中，第三方客户端使用的是客户端专用密码，也常被称作客户端授权码。企业微信扫码凭证、手机验证码、网页登录密码不能直接替代它。

2.1 生成步骤

1. 电脑网页版登录邮箱，进入 设置 → 邮箱绑定；部分界面可能使用“微信绑定”或安全相关标签。
2. 按页面要求完成身份绑定与验证，并确认 安全登录 已开启。
3. 在 客户端专用密码 区域选择 生成新密码。
4. 如果支持名称，使用便于识别的名称，例如 sparrow-notification-prod 或 office-foxmail。
5. 生成后立即保存到受控的密码或密钥管理位置，填入客户端的“密码”字段；不要期待以后能再次查看原文。

2.2 失效、更新与保存

• 停用某个专用密码后，该密码立即失效；关闭安全登录后，所有已生成的专用密码都会失效。不要把关闭安全登录当作排障手段。
• 更换密码后，同步更新应用的密钥配置和所有运行实例；仅修改本地配置文件，不会自动改变已启动进程中的配置。
• 检查复制时是否夹带空格、换行或引号；按生成结果准确保存，不要在业务代码中随意改写密码。
• 为不同应用分别生成凭据（若后台支持），便于独立撤销。密码不写入 Java 源码、Git、文章截图或公开日志。

生成路径与失效规则依据：企业微信 · 邮箱绑定微信与获取客户端专用密码。生成后立即保存是操作建议；本文不把“只显示一次”作为已核验的官方规则。

3. 服务器参数，一次填对

参数来源：企业微信现行官方设置说明。先确认企业是否启用信创邮箱；启用时应使用相应 xc 主机，且不支持 Exchange。旧版腾讯云指南曾列出 hwsmtp / hwimap / hwpop；现行 FAQ 已明确海外无需加 hw，本文不将旧地址作为默认方案。

• 用户名：完整邮箱地址，如 server@sparrowzoo.com，不是 server、显示姓名或企业微信用户 ID。
• 密码：安全登录场景下填写该成员生成的客户端专用密码。
• 发信认证：启用“SMTP 服务器需要身份验证”；基线配置中收发信使用同一账号与有效凭据。
• 服务器类型：不要把腾讯企业邮箱的 *.exmail.qq.com 与个人 QQ 邮箱的服务器混用。

465 的 SSL/TLS 与 STARTTLS 有什么区别？

本指南使用 465 的隐式 TLS：连接建立后直接进行 TLS 握手，对应 mail.smtp.ssl.enable=true。STARTTLS 则是在另一种连接模式中通过 SMTP 命令升级加密，不是将 465 上的 SSL 开关换一个名字。本文不把 587 当作已核验的腾讯企业邮箱推荐参数。

示例统一使用 smtp 协议配合 mail.smtp.* 属性。如果你改用 smtps，必须检查实现要求的 mail.smtps.* 属性前缀，避免端口、认证和超时配置没有生效。参见 JavaMail SMTP 属性说明。

4. Foxmail、Outlook 与其他客户端

客户端版本和操作系统不同，按钮名称会变化。下面以手动配置 IMAP + SMTP为统一核对方式；如果自动识别失败，手动填写服务器与端口。

4.1 Foxmail

1. 新建账号，选择腾讯企业邮箱或手动配置入口。
2. 使用账号密码方式时，输入完整邮箱地址及客户端专用密码；若当前版本提供企业邮箱扫码登录，可按其引导操作。
3. 收信类型选择 IMAP：服务器 imap.exmail.qq.com，端口 993，开启 SSL/TLS。
4. 发信服务器 smtp.exmail.qq.com，端口 465，开启 SSL/TLS 和身份验证。
5. 保存后分别验证收信和发信，不要只看账号添加成功的提示。

4.2 Outlook

1. 添加账户，选择高级设置、手动设置或 IMAP 入口（具体名称依版本而定）。
2. 收信服务器和发信服务器分别填写上述 IMAP、SMTP 参数。
3. 在提供相关选项的经典版本中，勾选“发送服务器需要验证”，使用与接收服务器相同的账号凭据。
4. 高级设置中核对 IMAP 993、SMTP 465，加密选择 SSL/TLS。
5. 测试收发。若版本不提供这些字段，使用该版本的手动 IMAP 指引，不照搬其他版本截图。

4.3 手机邮箱或 POP3 客户端

支持手动 IMAP/SMTP 的手机邮件应用使用同一组参数。确需 POP3 时，将收信改为 pop.exmail.qq.com:995，同时开启对应 POP/SMTP 权限；发信仍为 SMTP 465。第一次同步前，核对“保留服务器邮件副本”和删除策略，避免误把下载当成多端同步。

官方示例可参考腾讯云操作指南中的 Foxmail、Outlook 与移动客户端设置；本文按通用字段重组步骤，当前客户端界面优先。

5. JavaMail / Jakarta Mail：完整发送示例

5.1 先确认依赖属于哪个命名空间

下面代码使用 javax.mail，适用于已有 JavaMail 1.6.x API 的项目。采用 Jakarta Mail 2.x 的项目，应将全部 javax.mail 导入改为 jakarta.mail，并使用相匹配的运行时实现，例如 Eclipse Angus Mail。不要只加入 API 包后遗漏 SMTP 实现，也不要同时混用两套命名空间。Spring Boot 项目优先使用下一节的 starter 和项目自身的版本管理。

运行前，在应用实际启动环境中配置以下变量。本文不提供真实密码；环境变量也应通过受控部署配置注入，避免把密钥写进命令历史。

ExmailSmtpExample.java · 运行后发送一封测试邮件

import java.util.Date;
import java.util.Properties;
import javax.mail.Message;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;

public final class ExmailSmtpExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.trim().isEmpty()) {
            throw new IllegalArgumentException("Missing environment variable: " + name);
        }
        return value; // 原样使用凭据，不修改密码内容
    }

    public static void main(String[] args) throws Exception {
        String username = requiredEnv("MAIL_USERNAME");
        String password = requiredEnv("MAIL_CLIENT_PASSWORD");
        String recipient = requiredEnv("MAIL_TEST_TO");

        Properties props = new Properties();
        props.setProperty("mail.smtp.host", "smtp.exmail.qq.com");
        props.setProperty("mail.smtp.port", "465");
        props.setProperty("mail.smtp.auth", "true");
        props.setProperty("mail.smtp.ssl.enable", "true");
        props.setProperty("mail.smtp.ssl.checkserveridentity", "true");
        props.setProperty("mail.smtp.starttls.enable", "false");
        props.setProperty("mail.smtp.connectiontimeout", "10000");
        props.setProperty("mail.smtp.timeout", "10000");
        props.setProperty("mail.smtp.writetimeout", "10000");
        props.setProperty("mail.debug.auth", "false");

        Session session = Session.getInstance(props);
        session.setDebug(false);

        MimeMessage message = new MimeMessage(session);
        message.setFrom(new InternetAddress(username));
        message.setRecipient(Message.RecipientType.TO,
                new InternetAddress(recipient, true));
        message.setSubject("腾讯企业邮箱 SMTP 配置测试", "UTF-8");
        message.setText("如果收到此邮件，说明本次 SMTP 提交与投递链路已完成。", "UTF-8");
        message.setSentDate(new Date());

        Transport.send(message, username, password);
        System.out.println("SMTP submission completed; check the recipient inbox.");
    }
}

示例发件人 From 与认证账号一致，便于先建立可工作的基线。需要别名或代表其他地址发信时，先确认相应的代发权限。超时单位为毫秒，10000 是示例值，可按网络环境调整。不要设置 mail.smtp.ssl.trust=* 或关闭证书校验来“解决”TLS 错误。

属性依据：SMTP provider 配置；发送方法依据：Transport.send API。正常返回表示提交成功，最终是否到达收件箱仍需收件端确认。

5.2 只验证 SMTP 登录，不发送邮件

排查认证时，可在上例创建 session 后，以以下代码替换创建消息及发送部分；同时去掉读取 MAIL_TEST_TO 的那一行。这样可以将“认证成功”与“投递成功”分开验证。

try (Transport transport = session.getTransport("smtp")) {
    transport.connect("smtp.exmail.qq.com", 465, username, password);
    System.out.println("SMTP authentication succeeded.");
}

5.3 如果程序还需要 IMAP 收信

收信另建一个 Store；以下片段复用前面的 username、password，并额外导入 javax.mail.Store（Jakarta 项目使用对应包）。它只验证连接，不读取或删除邮件。

Properties imapProps = new Properties();
imapProps.setProperty("mail.imap.ssl.enable", "true");
imapProps.setProperty("mail.imap.ssl.checkserveridentity", "true");
imapProps.setProperty("mail.imap.connectiontimeout", "10000");
imapProps.setProperty("mail.imap.timeout", "10000");
Session imapSession = Session.getInstance(imapProps);

try (Store store = imapSession.getStore("imap")) {
    store.connect("imap.exmail.qq.com", 993, username, password);
    System.out.println("IMAP authentication succeeded.");
}

6. Spring Boot：交给 JavaMailSender 管理

在已经使用 Spring Boot parent 或 BOM 管理依赖版本的项目中，加入 mail starter；版本沿用当前项目，避免另引入一套不兼容的邮件实现。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mail</artifactId>
</dependency>

application.yml · 密码来自运行环境

spring:
  mail:
    host: smtp.exmail.qq.com
    port: 465
    protocol: smtp
    username: ${MAIL_USERNAME}
    password: ${MAIL_CLIENT_PASSWORD}
    default-encoding: UTF-8
    properties:
      "[mail.smtp.auth]": true
      "[mail.smtp.ssl.enable]": true
      "[mail.smtp.ssl.checkserveridentity]": true
      "[mail.smtp.starttls.enable]": false
      "[mail.smtp.connectiontimeout]": 10000
      "[mail.smtp.timeout]": 10000
      "[mail.smtp.writetimeout]": 10000
      "[mail.debug.auth]": false

方括号包围的键会作为完整 JavaMail 属性名传递。Spring Boot 官方特别提醒，部分邮件超时默认可能为无限等待，因此建议显式设置。若项目配置了 spring.mail.jndi-name，JNDI Session 会优先于其他 Session 设置，排查时也要确认是否存在自定义 JavaMailSender 覆盖自动配置。参见 Spring Boot Sending Email。

ExmailTestService.java · 在需要测试时显式调用

import org.springframework.beans.factory.annotation.Value;
import org.springframework.mail.SimpleMailMessage;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.stereotype.Service;

@Service
public class ExmailTestService {
    private final JavaMailSender sender;
    private final String from;

    public ExmailTestService(JavaMailSender sender,
                            @Value("${spring.mail.username}") String from) {
        this.sender = sender;
        this.from = from;
    }

    public void sendTest(String recipient) {
        SimpleMailMessage message = new SimpleMailMessage();
        message.setFrom(from);
        message.setTo(recipient);
        message.setSubject("腾讯企业邮箱配置测试");
        message.setText("请确认这封测试邮件已到达收件箱。");
        sender.send(message);
    }
}

将 recipient 设为你控制的测试邮箱，再由测试入口调用该方法；不要把示例直接做成无需鉴权、可任意指定收件人的公开接口。部署后还要确认实际启用的 profile、容器或服务进程已读取新的配置。

10. 常见问题：supervisord 启动后环境变量不生效

现象：终端中手动启动 Java 程序可以读取密码，通过 systemd 启动 supervisord 后，程序读不到 email_password 等变量，或仍使用旧值。

原因：systemd 管理的系统服务不会自动继承当前终端的 export，也不会自动加载该用户的 .bashrc、.bash_profile。环境应沿着 systemd → supervisord → Java 子进程传递。Supervisor 会继承启动环境，其全局或 [program:x] 中的 environment= 还可能覆盖同名值。参见 Supervisor 环境继承说明。

10.1 在 systemd 服务中声明变量

/usr/lib/systemd/system/supervisord.service 通常是安装包提供的原始文件；本机自定义完整 unit 放在 /etc/systemd/system/supervisord.service，同名文件优先。无需同时修改两处。先确认当前加载的文件及附加配置：

sudo systemctl show supervisord.service -p FragmentPath -p DropInPaths

# 查看安装包提供的原始配置
sudo vi /usr/lib/systemd/system/supervisord.service

# 编辑本机自定义配置；若文件不存在，先从原始 unit 复制并保留必要设置
sudo vi /etc/systemd/system/supervisord.service

以下沿用当前部署的路径与 Type=forking，关键是 [Service] 内的 Environment=。已有 unit 应保留原有 PIDFile、停止方式、用户和其他必要设置；如果只需追加变量，也可以执行 sudo systemctl edit supervisord.service，在 drop-in 中仅填写 [Service] 与 Environment=。

[Unit]
Description=Process Monitoring and Control Daemon
After=rc-local.service

[Service]
Type=forking
ExecStart=/usr/bin/supervisord -c /root/supervisord/supervisord.conf
RuntimeDirectory=supervisor
RuntimeDirectoryMode=755
Environment="authenticator_encrypt_key=111111" "email_password=111111" "mysql_sparrow_password=111111"

[Install]
WantedBy=multi-user.target

After=rc-local.service 只声明启动顺序，不会继承 rc.local 中导出的变量。RuntimeDirectory=supervisor 只负责创建运行目录，PID 文件和 socket 路径仍由 supervisord 配置决定；使用 PIDFile= 时须与 supervisord 的 pidfile 路径一致。

111111 全部为占位值，部署时替换；其中 email_password 应填写邮箱客户端专用密码。unit 中的 Environment= 是明文配置，实际密钥应使用受限的部署配置管理，不提交到公开仓库。Type=forking 要求 supervisord 以后台模式启动；若原服务使用 -n 或 nodaemon=true，保留匹配的前台服务类型，不要直接套用这里的 forking 设置。

10.2 变量名必须与程序读取方式一致

环境变量名区分大小写。当前部署使用 email_password，而本文前面的示例读取 MAIL_CLIENT_PASSWORD，两者不会自动对应。沿用当前部署变量名时，Java 读取改为 System.getenv("email_password")；Spring Boot 配置改为：

spring:
  mail:
    password: ${email_password}

上面的 YAML 只替换原配置中的 password 字段，其他 SMTP 参数和用户名配置保持完整。也可以保留原代码，在 service 中直接声明 MAIL_CLIENT_PASSWORD。不要写成 Environment=MAIL_CLIENT_PASSWORD=$email_password，systemd 的这个字段不进行 shell 变量展开。

10.3 重新加载 unit，再重启 supervisord

仅保存文件、执行 source、supervisorctl reread/update 或仅重启受管程序，都不能让已运行的 supervisord 获得新的 systemd 环境。需要让 systemd 重新读取 unit，再重新创建 supervisord 及其子进程：

sudo systemctl daemon-reload
sudo systemctl restart supervisord.service
sudo systemctl status supervisord.service --no-pager
sudo supervisorctl -c /root/supervisord/supervisord.conf status

重启 supervisord 会影响它管理的程序，应在可接受的重启窗口执行。检查各程序是否重新进入 RUNNING；未配置自动启动的程序需按实际服务名启动。daemon-reload 只加载配置，不会单独改变正在运行的进程环境。

10.4 在目标 Java 进程验证，避免只检查终端

在实际受 supervisord 管理的应用中临时检查变量是否存在，输出布尔值即可；终端执行 echo 得到的值不能证明服务进程已经收到配置。

String emailPassword = System.getenv("email_password");
System.out.println("email_password configured: "
        + (emailPassword != null && !emailPassword.trim().isEmpty()));

确认变量已传入后，再做 SMTP 认证测试。若仍读到旧值，核对是否连到了另一套 supervisord 实例、是否存在同名 environment= 覆盖，以及业务程序是否真正重启。