API 密钥管理
API 密钥用于验证您的 Zeabur Email API 请求。每个密钥可以设置不同的权限级别。
权限类型
Zeabur Email 提供三种权限级别：
| 权限类型 | 说明 | 适用场景 |
|---|---|---|
只读 (read_only) | 只能查询邮件和统计信息 | 数据分析、监控面板 |
只发送 (send_only) | 可以发送邮件和查询状态 | 生产环境应用（推荐） |
完全权限 (all) | 包含所有操作权限 | 管理工具、开发环境 |
⚠️
出于安全考虑，建议在生产环境使用「只发送」权限，避免使用「完全权限」。
创建 API 密钥
登录控制台
访问 Zeabur 控制台的 Zeabur Email 管理页面。
创建新密钥
- 进入「API 密钥管理」
- 点击「创建 API 密钥」
- 输入密钥名称（用于识别用途）
- 选择权限类型
- （可选）限制允许使用的域名
- 点击「创建」
保存密钥
🚫
密钥仅在创建时显示一次！请立即保存到安全的地方。
创建后，系统会显示完整的 API 密钥。复制并安全保存，您将无法再次查看完整密钥。
域名限制
您可以限制 API 密钥只能从特定域名发送邮件，增加安全性：
// 创建密钥时设置允许的域名
{
"name": "Production API Key",
"permission": "send_only",
"allowed_domains": ["yourdomain.com", "mail.yourdomain.com"]
}这样，即使密钥泄露，攻击者也无法使用未授权的域名发送邮件。
使用 API 密钥
HTTP 请求头
在所有 API 请求中包含密钥：
POST /api/v1/zsend/emails
Host: api.zeabur.com
Content-Type: application/json
Authorization: Bearer zs_your_api_key_here
{
"from": "[email protected]",
...
}代码示例
JavaScript
const apiKey = process.env.ZSEND_API_KEY;
const response = await fetch('https://api.zeabur.com/api/v1/zsend/emails', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + apiKey
},
body: JSON.stringify({
from: '[email protected]',
to: ['[email protected]'],
subject: '测试邮件',
html: '<p>测试内容</p>'
})
});Python
import os
import requests
api_key = os.environ.get('ZSEND_API_KEY')
response = requests.post(
'https://api.zeabur.com/api/v1/zsend/emails',
headers={
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + api_key
},
json={
'from': '[email protected]',
'to': ['[email protected]'],
'subject': '测试邮件',
'html': '<p>测试内容</p>'
}
)Go
package main
import (
"bytes"
"encoding/json"
"net/http"
"os"
)
func sendEmail() error {
apiKey := os.Getenv("ZSEND_API_KEY")
payload := map[string]interface{}{
"from": "[email protected]",
"to": []string{"[email protected]"},
"subject": "测试邮件",
"html": "<p>测试内容</p>",
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", "https://api.zeabur.com/api/v1/zsend/emails", bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer " + apiKey)
client := &http.Client{}
resp, err := client.Do(req)
return err
}轮换密钥
定期轮换 API 密钥是良好的安全实践：
建议每 90 天轮换一次密钥。
撤销密钥
如果密钥泄露或不再需要：
- 进入「API 密钥管理」
- 找到要删除的密钥
- 点击「删除」按钮
- 确认删除
⚠️
删除密钥后，使用该密钥的所有 API 请求将立即失败。
安全最佳实践
1. 使用环境变量
永远不要在代码中硬编码 API 密钥：
// ❌ 不推荐：不要硬编码
const apiKey = 'zs_xxxxxxxxxxxxxxxxxxxxxxxx';
// ✅ 推荐：使用环境变量
const apiKey = process.env.ZSEND_API_KEY;2. 使用最小权限原则
为不同的应用创建具有适当权限的独立密钥：
- 生产应用：只发送权限 + 域名限制
- 数据分析：只读权限
- 管理工具：完全权限（仅在必要时）
3. 监控密钥使用情况
在 Zeabur Email 控制台查看每个密钥的使用统计：
- 请求次数
- 发送邮件数量
- 错误率
发现异常使用立即撤销密钥。
4. 不要共享密钥
为每个应用、环境（开发/生产）创建独立的密钥，便于追踪和管理。
故障排查
401 Unauthorized
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}可能原因：
- API 密钥错误或已删除
- 请求头格式错误（应为
Authorization: Bearer <token>） - 密钥前后有空格或缺少
Bearer前缀
403 Forbidden
{
"error": "permission denied",
"message": "API key does not have permission to send from this domain"
}可能原因：
- 密钥权限不足（如使用只读密钥发送邮件）
- 发件域名不在密钥的允许列表中
- 域名未验证
429 Too Many Requests
{
"error": "too many requests",
"message": "Rate limit exceeded"
}解决方案：
- 实现请求限流和重试机制
- 考虑升级账号以获取更高的频率限制
- 使用批量发送 API 减少请求次数