MeterMailRs

MeterMailRs API 文档

API 概述

MeterMailRs 提供了一组简单的 RESTful API，允许您以编程方式访问临时邮箱服务。这些 API 可以用于查询邮件列表、获取特定邮件内容或删除邮件。

所有 API 返回 JSON 格式的数据，使用标准 HTTP 状态码表示请求结果。

使用限制

系统禁止使用某些特定的邮箱前缀，如 "admin"、"root" 等。如果尝试通过API访问这些前缀的邮箱，将收到 403 Forbidden 错误。

禁用前缀错误示例

{
  "error": "不允许使用该邮箱前缀",
  "code": "forbidden_prefix"
}

注意：错误消息会根据请求头中的 Accept-Language 返回中文或英文。

基础 URL

所有 API 请求都使用以下基础 URL：

http://您的服务器地址:端口

例如：http://localhost:3000 或 https://mail.yourdomain.com

API 端点

1. 获取可用域名列表

GET /api/domains

获取当前系统所有可用的活跃域名。如果不提供 API Key，只返回公开的域名；如果请求头带有合法的 API Key，将同时返回公开和私有的域名。

示例请求

GET /api/domains

示例响应

{
  "public_domains": [
    "127.0.0.1",
    "rien.ccc"
  ],
  "private_domains": [
    "localhost"
  ],
  "all_available_domains": [
    "127.0.0.1",
    "rien.ccc",
    "localhost"
  ]
}

2. 创建邮箱 (支持私有域名)

POST /api/mailboxes

通过 API 创建邮箱。需要使用管理员生成的 API Key 进行身份验证。此接口可以在任何域名下创建邮箱，包括被标记为私有的域名。

认证方式

在请求头中添加: Authorization: Bearer <您的API Key>

示例请求

{
  "id": "testpriv",
  "domain": "localhost"
}

示例响应

{
  "success": true,
  "address": "testpriv@localhost",
  "expires_in_minutes": 10
}

3. 获取邮箱邮件列表

GET /api/mails/:mailboxAddr

获取指定邮箱地址中的所有邮件列表。:mailboxAddr 为完整邮箱地址（如 zdugawlb@localhost），需要进行 URL 编码。

示例请求

GET /api/mails/zdugawlb%40localhost

示例响应

{
  "mails": [
    {
      "to": "zdugawlb@localhost",
      "from": "test@example.com",
      "subject": "测试邮件",
      "text": "你好，这是一封测试邮件",
      "html": "",
      "date": "2025-04-15T12:02:26.000Z",
      "attachments": [],
      "raw": "..."
    },
    // 更多邮件...
  ]
}

4. 获取指定邮件

GET /api/mails/:mailboxAddr/:idx

获取指定邮箱中特定索引的邮件。:mailboxAddr 为完整邮箱地址，需要 URL 编码；:idx 为邮件在列表中的索引（从0开始）。

示例请求

GET /api/mails/zdugawlb%40localhost/0

示例响应 - 成功

{
  "mail": {
    "to": "zdugawlb@localhost",
    "from": "test@example.com",
    "subject": "测试邮件",
    "text": "你好，这是一封测试邮件",
    "html": "",
    "date": "2025-04-15T12:02:26.000Z",
    "attachments": [],
    "raw": "..."
  }
}

示例响应 - 邮件不存在

{
  "error": "邮件不存在或已过期"
}

5. 删除指定邮件

DELETE /api/mails/:mailboxAddr/:idx

删除指定邮箱中特定索引的邮件。:mailboxAddr 为完整邮箱地址，需要 URL 编码；:idx 为邮件在列表中的索引（从0开始）。

示例请求

DELETE /api/mails/zdugawlb%40localhost/0

示例响应

{
  "success": true
}

使用示例

cURL 示例

获取可用域名

curl -X GET "http://localhost:3000/api/domains" \
  -H "Authorization: Bearer sk-YOUR-API-KEY"

创建私有域名邮箱

curl -X POST "http://localhost:3000/api/mailboxes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR-API-KEY" \
  -d '{"id": "test", "domain": "yourdomain.com"}'

获取邮件列表

curl -X GET "http://localhost:3000/api/mails/zdugawlb%40localhost"

获取特定邮件

curl -X GET "http://localhost:3000/api/mails/zdugawlb%40localhost/0"

删除邮件

curl -X DELETE "http://localhost:3000/api/mails/zdugawlb%40localhost/0"

JavaScript 示例

// 获取邮件列表
async function getMailList(mailbox) {
  const response = await fetch(`http://localhost:3000/api/mails/${encodeURIComponent(mailbox)}`);
  const data = await response.json();
  return data.mails;
}

// 获取特定邮件
async function getMail(mailbox, index) {
  const response = await fetch(`http://localhost:3000/api/mails/${encodeURIComponent(mailbox)}/${index}`);
  if (response.ok) {
    const data = await response.json();
    return data.mail;
  }
  return null;
}

// 删除邮件
async function deleteMail(mailbox, index) {
  const response = await fetch(
    `http://localhost:3000/api/mails/${encodeURIComponent(mailbox)}/${index}`,
    { method: 'DELETE' }
  );
  const data = await response.json();
  return data.success;
}

Python 示例

import requests
import urllib.parse

BASE_URL = "http://localhost:3000"

# 获取邮件列表
def get_mail_list(mailbox):
    mailbox_encoded = urllib.parse.quote(mailbox)
    response = requests.get(f"{BASE_URL}/api/mails/{mailbox_encoded}")
    return response.json()['mails'] if response.status_code == 200 else []

# 获取特定邮件
def get_mail(mailbox, index):
    mailbox_encoded = urllib.parse.quote(mailbox)
    response = requests.get(f"{BASE_URL}/api/mails/{mailbox_encoded}/{index}")
    return response.json()['mail'] if response.status_code == 200 else None

# 删除邮件
def delete_mail(mailbox, index):
    mailbox_encoded = urllib.parse.quote(mailbox)
    response = requests.delete(f"{BASE_URL}/api/mails/{mailbox_encoded}/{index}")
    return response.json()['success'] if response.status_code == 200 else False