# SMTP邮件配置系统

这是一个为WordPress主题开发的SMTP邮件配置系统，提供完整的邮件发送功能。

## 功能特性

### 1. SMTP邮件配置
- 支持主流邮件服务商（Gmail、QQ邮箱、163邮箱、阿里云邮箱等）
- 灵活的加密方式配置（TLS/SSL/无加密）
- 系统诊断工具：检查服务器环境和PHP扩展支持
- 连接测试功能：验证SMTP服务器连接状态
- 测试邮件发送功能
- 详细的错误提示和调试信息

### 2. 安全特性
- 配置验证和错误提示
- 数据清理和验证
- 安全的密码存储

## 文件结构

```
inc/smtp/
├── smtp-config.php      # SMTP核心配置文件
├── smtp-admin.php       # 后台管理页面
├── smtp-diagnostic.php  # SMTP诊断工具
└── README.md           # 使用说明文档
```

## 配置步骤

### 1. 访问SMTP设置页面

1. 登录WordPress后台
2. 进入 **设置** → **SMTP邮件设置**
3. 配置相关参数

### 2. SMTP服务器设置

- **SMTP主机**：邮件服务商的SMTP服务器地址
- **SMTP端口**：通常为587（TLS）或465（SSL）
- **加密方式**：推荐使用TLS或SSL
- **SMTP用户名**：通常是您的邮箱地址
- **SMTP密码**：邮箱密码或应用专用密码
- **发件人邮箱**：邮件的发件人地址
- **发件人姓名**：邮件的发件人显示名称

### 3. 常用邮件服务商配置

#### Gmail配置
```
SMTP主机: smtp.gmail.com
SMTP端口: 587
加密方式: TLS
用户名: your-email@gmail.com
密码: 应用专用密码（需开启两步验证）
```

#### QQ邮箱配置
```
SMTP主机: smtp.qq.com
SMTP端口: 587 或 465
加密方式: TLS 或 SSL
用户名: your-email@qq.com
密码: 授权码（需在QQ邮箱设置中获取）
```

#### 163邮箱配置
```
SMTP主机: smtp.163.com
SMTP端口: 587 或 465
加密方式: TLS 或 SSL
用户名: your-email@163.com
密码: 授权码（需在163邮箱设置中获取）
```

#### 阿里云邮箱配置
```
SMTP主机: smtp.mxhichina.com
SMTP端口: 587 或 465
加密方式: TLS 或 SSL
用户名: your-email@yourdomain.com
密码: 授权码（必须使用授权码，不能使用登录密码）
```

#### hMailServer 自建邮箱配置
```
SMTP主机: 您的邮件服务器域名或IP地址
SMTP端口: 25 (无加密) / 587 (TLS) / 465 (SSL)
加密方式: None / TLS / SSL（根据服务器配置选择）
用户名: 完整邮箱地址或用户名（取决于hMailServer配置）
密码: 邮箱账户密码
```

**hMailServer 配置注意事项：**
- 确保hMailServer服务已启动并正常运行
- 检查SMTP服务是否已在hMailServer中启用
- 确认防火墙允许相应端口的连接
- 如果使用域名，确保DNS解析正确
- 建议使用TLS加密（端口587）以提高安全性

### 3. 测试SMTP连接

配置完成后，点击 **发送测试邮件** 按钮验证配置是否正确。

系统会发送一封测试邮件到管理员邮箱，如果配置正确，您将收到测试邮件。如果发送失败，系统会显示详细的错误信息帮助您排查问题。

## 使用说明

### 系统诊断

在SMTP设置页面点击"系统诊断"按钮，系统会检查：
- PHP版本和必要扩展
- OpenSSL支持情况
- 网络连接能力
- SSL/TLS证书信息

### 测试SMTP连接

点击"测试连接"按钮，系统会尝试连接到SMTP服务器，验证：
- 服务器地址和端口是否可达
- SSL/TLS加密是否正常
- 连接响应时间

### 发送测试邮件

点击"发送测试邮件"按钮，系统会向管理员邮箱发送一封测试邮件。如果配置正确，您将收到测试邮件。

### 在代码中发送邮件

配置完SMTP后，您可以在WordPress中正常使用 `wp_mail()` 函数发送邮件：

```php
<?php
// 发送邮件示例
$to = 'recipient@example.com';
$subject = '邮件主题';
$message = '邮件内容';
$headers = array('Content-Type: text/html; charset=UTF-8');

$sent = wp_mail($to, $subject, $message, $headers);

if ($sent) {
    echo '邮件发送成功';
} else {
    echo '邮件发送失败';
}
?>
```

## 安全特性

- **配置验证**：系统会验证SMTP配置的完整性
- **数据清理**：所有配置数据都经过WordPress安全函数处理
- **密码保护**：SMTP密码安全存储在WordPress数据库中

## 故障排除

### 推荐的诊断步骤

遇到SMTP问题时，建议按以下顺序进行诊断：

1. **运行系统诊断**
   - 点击"系统诊断"按钮
   - 检查PHP版本和扩展支持
   - 确认OpenSSL和网络功能正常

2. **测试服务器连接**
   - 点击"测试连接"按钮
   - 验证能否连接到SMTP服务器
   - 检查SSL/TLS握手是否成功

3. **发送测试邮件**
   - 在连接测试成功后，点击"发送测试邮件"
   - 查看详细的错误信息和调试输出

### 常见问题解决方案

#### 连接超时或拒绝连接
- 检查SMTP服务器地址和端口
- 确认服务器防火墙设置
- 验证网络连接是否正常

#### SSL/TLS握手失败
- 确认加密方式设置正确（TLS/SSL）
- 检查OpenSSL版本和支持的协议
- 尝试不同的端口（587用于TLS，465用于SSL）

#### 认证失败 (526 Authentication failure)
**⚠️ 重要：大多数邮箱服务需要使用授权码而不是登录密码！**

**阿里云邮箱：**
- 必须使用授权码，不能使用登录密码
- 获取方式：登录阿里云邮箱 → 设置 → 账户安全 → 生成授权码
- 用户名：完整邮箱地址

**QQ邮箱：**
- 需要开启SMTP服务并使用授权码
- 获取方式：QQ邮箱设置 → 账户 → POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务
- 生成授权码后使用授权码作为密码

**163邮箱：**
- 需要开启客户端授权密码
- 获取方式：163邮箱设置 → POP3/SMTP/IMAP → 开启服务并获取授权码

**Gmail：**
- 需要开启两步验证并使用应用专用密码
- 获取方式：Google账户设置 → 安全性 → 应用专用密码

**通用检查项：**
- 确认用户名格式正确（通常是完整邮箱地址）
- 检查是否已在邮箱设置中开启SMTP服务
- 验证授权码/应用密码是否正确输入

#### 邮件发送失败但连接正常
- 检查发件人邮箱设置
- 确认邮箱配额未超限
- 验证收件人邮箱地址有效性

#### hMailServer 自建邮箱常见问题
**连接问题：**
- 确认hMailServer服务状态：检查Windows服务中的hMailServer是否正在运行
- 验证SMTP服务启用：在hMailServer管理器中确认SMTP已启用
- 检查端口配置：确认hMailServer中配置的SMTP端口与WordPress设置一致
- 防火墙设置：确保Windows防火墙允许SMTP端口通信

**认证问题：**
- 用户名格式：可能需要使用完整邮箱地址或仅用户名部分
- 域名配置：确认邮箱域名在hMailServer中已正确配置
- 账户状态：检查邮箱账户是否已启用且未被锁定

**SSL/TLS问题：**
- 证书配置：如使用SSL/TLS，确保hMailServer中已正确配置SSL证书
- 端口匹配：SSL通常使用465端口，TLS使用587端口
- 加密设置：确认hMailServer的加密设置与WordPress配置匹配

**网络问题：**
- DNS解析：如使用域名，确保DNS解析正确指向邮件服务器
- 网络连通性：测试从WordPress服务器到hMailServer的网络连接
- 路由配置：检查网络路由是否正确配置

### 常见问题

#### 1. 邮件发送失败
- 检查SMTP配置是否正确
- 确认邮箱密码或授权码是否有效
- 检查服务器是否允许SMTP连接
- 查看WordPress调试日志
- 确认防火墙没有阻止SMTP端口
- 验证邮件服务商是否支持SMTP发送

### 调试模式

在`wp-config.php`中启用调试模式：

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

然后查看`/wp-content/debug.log`文件获取详细错误信息。

## 更新日志

### v1.1.2
- 新增hMailServer自建邮箱SMTP配置支持
- 添加hMailServer配置说明和注意事项
- 完善hMailServer常见问题的故障排除指南
- 包含连接、认证、SSL/TLS和网络问题的解决方案

### v1.1.1
- 修复open_basedir限制导致的错误日志写入问题
- 增强526认证失败错误的诊断和解决方案提示
- 在管理界面添加授权码使用的重要提示
- 完善各大邮箱服务商的授权码获取指南
- 优化错误信息显示，突出显示认证失败的解决方案

### v1.1.0
- 新增系统诊断工具，检查PHP环境和扩展支持
- 新增SMTP连接测试功能，验证服务器连接状态
- 增强错误报告，提供详细的调试信息和日志
- 改进测试界面，提供三级诊断步骤
- 优化SSL/TLS连接处理和证书信息显示
- 增加连接超时设置和性能优化

### v1.0.0
- 初始版本发布
- 支持基础SMTP配置
- 提供测试邮件发送功能
- 包含详细的错误提示和调试信息

## 技术支持

如果您在使用过程中遇到问题，请：

1. 查看本文档的故障排除部分
2. 检查WordPress调试日志
3. 联系主题开发者获取技术支持

---

**注意**：请妥善保管您的邮箱密码和授权码，不要在不安全的环境中暴露这些信息。