BeatMail — 开放 API 使用指南

OPEN API

BeatMail 开放 API 使用指南

当前开放接口沿用稳定的 action= 路由：/api/index.php?action=...。适合外部脚本、工具和学习研究调用。

BASE

基础地址与响应格式

把示例里的 https://你的域名 替换为你的站点域名。如果部署在子目录，例如 /mail/，Base URL 应包含子目录。

BASE_URL = "https://你的域名/api/index.php"
# 子目录示例："https://你的域名/mail/api/index.php"

接口统一返回 JSON：

{
  "ok": true,
  "data": {}
}

失败时：

{
  "ok": false,
  "error": "错误说明"
}

AUTH

API 鉴权

鉴权默认已开启。本站页面自身的请求免密放行，外部脚本调用必须携带密钥：

Authorization: Bearer YOUR_API_KEY

密钥与开关都在 web/api/config.php：

define('API_AUTH_ENABLED', true);   // 关掉则 API 完全公开
define('API_KEY', '请替换成你的密钥');
define('API_ALLOW_SAME_ORIGIN', true); // 本站页面免密

无密钥或密钥错误时返回 401：

{
  "ok": false,
  "error": "缺少凭证。外部调用需携带 Authorization: Bearer <API_KEY>"
}

action=health 始终公开，方便部署后探活。注意：创建邮箱返回的 token 是读取该邮箱邮件的业务 token，不等于 API 鉴权密钥。

RATE LIMIT

调用频率限制

按客户端 IP 固定窗口限流，默认配置：

一般接口：60 次 / 分钟
action=create（创建邮箱代价高）：10 次 / 分钟

每个响应都会带上余量头，超限时返回 429 并附 Retry-After：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42

// 超限时
HTTP/1.1 429
Retry-After: 37
{
  "ok": false,
  "error": "请求过于频繁，请稍后再试",
  "retry_after": 37
}

阈值可在 api/config.php 的 RATE_LIMIT_MAX / RATE_LIMIT_CREATE_MAX 调整。

ENDPOINTS

接口列表

action	方法	说明	参数
`health`	GET	健康检查	无
`domains`	GET	获取全部域名	无
`create`	POST	创建邮箱	`service`、`domain`、`name`、`email`
`messages`	GET	读取收件箱列表	`email`、`token`
`message`	GET	读取单封邮件详情	`email`、`token`、`id`

EMAIL CONTRACT

邮箱 `@` / `%40` 规则

业务数据、JSON body、保存变量里都使用字面量邮箱：demo01@bltiwd.com。
放进 URL query 时，@ 被编码成 %40 是正确的。
不要双重编码成 %2540。
推荐让 URLSearchParams、Python requests、PHP http_build_query 或 curl --data-urlencode 自动编码一次。

EXAMPLES

curl 调用示例

把 YOUR_API_KEY 换成 api/config.php 里的密钥。

健康检查（无需密钥）

curl -s "https://你的域名/api/index.php?action=health"

获取域名

curl -s "https://你的域名/api/index.php?action=domains" \
  -H "Authorization: Bearer YOUR_API_KEY"

创建邮箱

curl -s -X POST "https://你的域名/api/index.php?action=create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"service":"temp-mail-io","domain":"bltiwd.com","name":"demo01"}'

读取收件箱

curl -s "https://你的域名/api/index.php?action=messages&email=demo01%40bltiwd.com&token=TOKEN" \
  -H "Authorization: Bearer YOUR_API_KEY"

PYTHON

Python 调用示例

import requests

BASE = "https://你的域名/api/index.php"
API_KEY = "YOUR_API_KEY"  # 见 api/config.php

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
}

created = requests.post(
    BASE,
    params={"action": "create"},
    json={
        "service": "temp-mail-io",
        "domain": "bltiwd.com",
        "name": "demo01",
    },
    headers=headers,
    timeout=45,
).json()

if not created.get("ok"):
    raise RuntimeError(created.get("error"))

mailbox = created["data"]["mailbox"]  # 字面量 @，例如 demo01@bltiwd.com
token = created["data"]["token"]

inbox = requests.get(
    BASE,
    params={
        "action": "messages",
        "email": mailbox,  # requests 会把 @ 编码为 %40 一次
        "token": token,
    },
    headers=headers,
    timeout=45,
).json()

print(inbox)

PHP

PHP 调用示例

<?php

$base = 'https://你的域名/api/index.php';
$apiKey = 'YOUR_API_KEY'; // 见 api/config.php

function beatmail_headers($apiKey) {
    return [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $apiKey,
    ];
}

function beatmail_post($base, $action, array $body, array $headers) {
    $url = $base . '?' . http_build_query(['action' => $action]);
    $context = stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => implode("\r\n", $headers),
            'content' => json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
            'timeout' => 45,
        ],
    ]);
    return json_decode(file_get_contents($url, false, $context), true);
}

function beatmail_get($base, array $query, array $headers) {
    $url = $base . '?' . http_build_query($query); // 会把 @ 编码为 %40 一次
    $context = stream_context_create([
        'http' => [
            'method' => 'GET',
            'header' => implode("\r\n", $headers),
            'timeout' => 45,
        ],
    ]);
    return json_decode(file_get_contents($url, false, $context), true);
}

$headers = beatmail_headers($apiKey);

$created = beatmail_post($base, 'create', [
    'service' => 'temp-mail-io',
    'domain' => 'bltiwd.com',
    'name' => 'demo01',
], $headers);

if (empty($created['ok'])) {
    throw new RuntimeException($created['error'] ?? 'create failed');
}

$mailbox = $created['data']['mailbox']; // 字面量 @
$token = $created['data']['token'];

$inbox = beatmail_get($base, [
    'action' => 'messages',
    'email' => $mailbox,
    'token' => $token,
], $headers);

print_r($inbox);

FLOW