API 接口文档

百佳邮件服务 API 完整使用指南

📨 获取最新一封邮件

📋 接口信息

属性	值
请求方法	GET / POST
接口地址	/api/mail-new
功能描述	获取最新的一封邮件，可自行从邮件中正则提取验证码

📝 请求参数

参数名	类型	必填	说明
refresh_token	string	✅	用于身份验证的 refresh_token
client_id	string	✅	客户端 ID
email	string	✅	邮箱地址
mailbox	string	✅	邮箱文件夹 (INBOX / Junk)
response_type	string	❌	返回格式 (json / html)，默认 json

🐍 Python 代码示例

GET 请求

import requests

# GET 请求示例 - 参数直接拼接到 URL 中
refresh_token = "your_refresh_token"
client_id = "your_client_id"
email = "your_email@example.com"
mailbox = "INBOX"
response_type = "json"

url = f"http://oauth.bj65.com/api/mail-new?refresh_token={refresh_token}&client_id={client_id}&email={email}&mailbox={mailbox}&response_type={response_type}"

try:
    response = requests.get(url)
    response.raise_for_status()
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

POST 请求

import requests
import json

# POST 请求示例
url = "http://oauth.bj65.com/api/mail-new"
headers = {
    "Content-Type": "application/json"
}
data = {
    "refresh_token": "your_refresh_token",
    "client_id": "your_client_id",
    "email": "your_email@example.com",
    "mailbox": "INBOX",
    "response_type": "json"
}

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    result = response.json()
    print(result)
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

---

📂 获取全部邮件

📋 接口信息

属性	值
请求方法	GET / POST
接口地址	/api/mail-all
功能描述	获取全部邮件，自动提取6位数字验证码

📝 请求参数

参数名	类型	必填	说明
refresh_token	string	✅	用于身份验证的 refresh_token
client_id	string	✅	客户端 ID
email	string	✅	邮箱地址
mailbox	string	✅	邮箱文件夹 (INBOX / Junk)

🐍 Python 代码示例

GET 请求

import requests

# GET 请求示例 - 参数直接拼接到 URL 中
refresh_token = "your_refresh_token"
client_id = "your_client_id"
email = "your_email@example.com"
mailbox = "INBOX"

url = f"http://oauth.bj65.com/api/mail-all?refresh_token={refresh_token}&client_id={client_id}&email={email}&mailbox={mailbox}"

try:
    response = requests.get(url)
    response.raise_for_status()
    data = response.json()
    print(f"获取到 {len(data)} 封邮件")
    for mail in data:
        print(f"主题: {mail.get('subject', 'N/A')}")
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

POST 请求

import requests

# POST 请求示例
url = "http://oauth.bj65.com/api/mail-all"
headers = {
    "Content-Type": "application/json"
}
data = {
    "refresh_token": "your_refresh_token",
    "client_id": "your_client_id",
    "email": "your_email@example.com",
    "mailbox": "INBOX"
}

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    result = response.json()
    print(f"获取到 {len(result)} 封邮件")
    for mail in result:
        print(f"主题: {mail.get('subject', 'N/A')}")
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

---

🗑️ 清空收件箱

📋 接口信息

属性	值
请求方法	GET / POST
接口地址	/api/process-inbox
功能描述	清空收件箱中的所有邮件

📝 请求参数

参数名	类型	必填	说明
refresh_token	string	✅	用于身份验证的 refresh_token
client_id	string	✅	客户端 ID
email	string	✅	邮箱地址

🐍 Python 代码示例

GET 请求

import requests

# GET 请求示例 - 参数直接拼接到 URL 中
refresh_token = "your_refresh_token"
client_id = "your_client_id"
email = "your_email@example.com"

url = f"http://oauth.bj65.com/api/process-inbox?refresh_token={refresh_token}&client_id={client_id}&email={email}"

try:
    response = requests.get(url)
    response.raise_for_status()
    data = response.json()
    print("收件箱清空成功!")
    print(data)
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

POST 请求

import requests

# POST 请求示例
url = "http://oauth.bj65.com/api/process-inbox"
headers = {
    "Content-Type": "application/json"
}
data = {
    "refresh_token": "your_refresh_token",
    "client_id": "your_client_id",
    "email": "your_email@example.com"
}

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    result = response.json()
    print("收件箱清空成功!")
    print(result)
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

---

🗑️ 清空垃圾箱

📋 接口信息

属性	值
请求方法	GET / POST
接口地址	/api/process-junk
功能描述	清空垃圾箱中的所有邮件

📝 请求参数

参数名	类型	必填	说明
refresh_token	string	✅	用于身份验证的 refresh_token
client_id	string	✅	客户端 ID
email	string	✅	邮箱地址

🐍 Python 代码示例

GET 请求

import requests

# GET 请求示例 - 参数直接拼接到 URL 中
refresh_token = "your_refresh_token"
client_id = "your_client_id"
email = "your_email@example.com"

url = f"http://oauth.bj65.com/api/process-junk?refresh_token={refresh_token}&client_id={client_id}&email={email}"

try:
    response = requests.get(url)
    response.raise_for_status()
    data = response.json()
    print("垃圾箱清空成功!")
    print(data)
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

POST 请求

import requests

# POST 请求示例
url = "http://oauth.bj65.com/api/process-junk"
headers = {
    "Content-Type": "application/json"
}
data = {
    "refresh_token": "your_refresh_token",
    "client_id": "your_client_id",
    "email": "your_email@example.com"
}

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    result = response.json()
    print("垃圾箱清空成功!")
    print(result)
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

---

📤 发送邮件(暂不开放)

📋 接口信息

属性	值
请求方法	GET / POST
接口地址	/api/send-mail
功能描述	发送邮件，支持纯文本或 HTML 格式

📝 请求参数

参数名	类型	必填	说明
refresh_token	string	✅	用于身份验证的 refresh_token
client_id	string	✅	客户端 ID
email	string	✅	发件人邮箱地址
to	string	✅	收件人邮箱地址
subject	string	✅	邮件主题
text	string	❌	纯文本内容（与 html 二选一）
html	string	❌	HTML 格式内容（与 text 二选一）
send_password	string	❌	发送密码（可选，增强安全性）

安全提示

为增强接口安全性，防止滥用，现已支持密码验证功能。您可以通过在环境变量中配置 SEND_PASSWORD 来启用此功能。启用后，请求时需提供正确的 SEND_PASSWORD 参数方可访问。

🐍 Python 代码示例

纯文本邮件 - GET

import requests

# GET 请求发送纯文本邮件 - 参数直接拼接到 URL 中
refresh_token = "your_refresh_token"
client_id = "your_client_id"
email = "your_email@example.com"
to = "recipient@example.com"
subject = "测试邮件"
text = "这是一封测试邮件"

url = f"http://oauth.bj65.com/api/send-mail?refresh_token={refresh_token}&client_id={client_id}&email={email}&to={to}&subject={subject}&text={text}"

try:
    response = requests.get(url)
    response.raise_for_status()
    data = response.json()
    print("邮件发送成功!")
    print(data)
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

HTML 邮件 - POST

import requests

# POST 请求发送 HTML 邮件
url = "http://oauth.bj65.com/api/send-mail"
headers = {
    "Content-Type": "application/json"
}
data = {
    "refresh_token": "your_refresh_token",
    "client_id": "your_client_id",
    "email": "your_email@example.com",
    "to": "recipient@example.com",
    "subject": "HTML 测试邮件",
    "html": """
    <html>
        <head><title>测试邮件</title></head>
        <body>
            <h2>🎉 欢迎使用百佳邮件服务</h2>
            <p>这是一封 <strong>HTML 格式</strong> 的测试邮件。</p>
            <ul>
                <li>✅ 支持 HTML 格式</li>
                <li>✅ 支持纯文本格式</li>
                <li>✅ 自动验证码提取</li>
            </ul>
        </body>
    </html>
    """
}

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    result = response.json()
    print("HTML 邮件发送成功!")
    print(result)
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

带密码验证

import requests

# 带安全密码的邮件发送
url = "http://oauth.bj65.com/api/send-mail"
headers = {
    "Content-Type": "application/json"
}
data = {
    "refresh_token": "your_refresh_token",
    "client_id": "your_client_id",
    "email": "your_email@example.com",
    "to": "recipient@example.com",
    "subject": "安全邮件",
    "text": "这是一封带有安全验证的邮件",
    "send_password": "your_send_password"  # 如果启用了密码验证
}

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    result = response.json()
    print("安全邮件发送成功!")
    print(result)
except requests.exceptions.RequestException as e:
    print(f"请求错误: {e}")

---

📖 使用说明

🔐 认证信息获取

• refresh_token 和 client_id 需要通过 OAuth 认证流程获取
• 建议将认证信息存储在安全的配置文件中，不要硬编码在代码中

⚡ 最佳实践

• 使用 POST 请求处理敏感数据
• 添加适当的错误处理和重试机制
• 对于批量操作，建议添加请求间隔避免频率限制

🛡️ 安全建议

• 定期更新 refresh_token
• 使用 HTTPS 确保数据传输安全
• 启用发送密码验证功能防止接口滥用