🚀 GoMail API 开发者文档 🚀

基于Token认证的临时邮箱API接口,支持创建邮箱、获取邮件、下载附件等功能
简单易用 · 安全可靠 · 完整功能

📋 API 概览

所有API请求都需要Token认证,支持RESTful风格的HTTP请求

创建邮箱

快速创建临时邮箱地址

POST

获取邮件

获取邮箱的邮件列表

GET

邮件详情

获取邮件完整内容

GET

下载附件

下载邮件附件文件

GET
认证方式
所有API请求都需要在HTTP头中包含有效的API Token

请求头格式:

Authorization: Bearer gm_your_token_here

如何获取Token?

  1. 1. 登录管理后台
  2. 2. 进入"Token管理"页面
  3. 3. 创建新的API Token
  4. 4. 设置使用限制和有效期

Token特点

  • • 支持使用次数限制
  • • 支持过期时间设置
  • • 可随时启用/禁用
  • • 只显示一次,请妥善保存

🔗 API 接口详情

完整的API接口说明,包含请求参数和响应格式

POST创建临时邮箱
/api/external/mailbox
创建一个新的临时邮箱地址,可自定义前缀和域名

请求体 (JSON):

JSON
{
  "prefix": "test",        // 可选:邮箱前缀
  "domain": "184772.xyz"   // 可选:邮箱域名
}

响应示例:

JSON
{
  "success": true,
  "data": {
    "id": "mailbox_id",
    "email": "test@184772.xyz",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "expiresAt": "2024-01-02T00:00:00.000Z",
    "isActive": true
  },
  "message": "Mailbox created successfully",
  "remainingUsage": 99
}
GET获取邮件列表
/api/external/emails/{email}
获取指定邮箱的所有邮件列表

路径参数:

email - 邮箱地址 (例如: test@184772.xyz)

响应示例:

JSON
{
  "success": true,
  "data": {
    "email": "test@184772.xyz",
    "totalCount": 2,
    "emails": [
      {
        "id": "email_id",
        "fromAddress": "sender@example.com",
        "subject": "测试邮件",
        "receivedAt": "2024-01-01T12:00:00.000Z",
        "isRead": false,
        "size": 1024,
        "hasAttachments": true
      }
    ]
  },
  "message": "Found 2 emails",
  "remainingUsage": 98
}
GET获取邮件详情
/api/external/email/{id}
获取指定邮件的完整内容,包括附件信息

路径参数:

id - 邮件ID

响应示例:

JSON
{
  "success": true,
  "data": {
    "id": "email_id",
    "fromAddress": "sender@example.com",
    "toAddress": "test@184772.xyz",
    "subject": "测试邮件",
    "textContent": "邮件文本内容",
    "htmlContent": "<p>邮件HTML内容</p>",
    "receivedAt": "2024-01-01T12:00:00.000Z",
    "isRead": false,
    "size": 1024,
    "attachments": [
      {
        "id": "attachment_id",
        "filename": "document.pdf",
        "contentType": "application/pdf",
        "size": 2048,
        "downloadUrl": "/api/external/attachment/attachment_id"
      }
    ]
  },
  "message": "Email details retrieved successfully",
  "remainingUsage": 97
}
GET下载附件
/api/external/attachment/{id}
下载指定的邮件附件文件

路径参数:

id - 附件ID

响应:

返回附件的二进制内容,包含适当的 Content-Type 和 Content-Disposition 头
GET获取Token信息
/api/external/mailbox
获取当前Token的使用信息和状态

响应示例:

JSON
{
  "success": true,
  "data": {
    "tokenName": "API客户端1",
    "usageLimit": 100,
    "usageCount": 3,
    "remainingUsage": 97,
    "isActive": true,
    "expiresAt": "2024-12-31T23:59:59.000Z",
    "lastUsedAt": "2024-01-01T12:00:00.000Z",
    "usable": true,
    "reason": null
  },
  "message": "Token information retrieved"
}
❌ 错误响应
当请求失败时,API会返回相应的错误信息

错误响应格式:

JSON
{
  "success": false,
  "error": "错误描述",
  "message": "详细错误信息"
}

常见错误代码:

400请求参数错误
401Token无效或缺失
403Token已禁用或过期
404资源不存在

💻 代码示例

多种编程语言的完整示例代码

JavaScript / Node.js
使用fetch API调用GoMail接口的完整示例
JavaScript
const API_BASE = 'https://184772.xyz';
const API_TOKEN = 'gm_your_token_here';

// 创建邮箱
async function createMailbox() {
  const response = await fetch(`${API_BASE}/api/external/mailbox`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prefix: 'test',
      domain: '184772.xyz'
    })
  });

  const data = await response.json();
  return data;
}

// 获取邮件列表
async function getEmails(email) {
  const response = await fetch(`${API_BASE}/api/external/emails/${email}`, {
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`
    }
  });

  const data = await response.json();
  return data;
}

// 获取邮件详情
async function getEmailDetail(emailId) {
  const response = await fetch(`${API_BASE}/api/external/email/${emailId}`, {
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`
    }
  });

  const data = await response.json();
  return data;
}

// 使用示例
async function main() {
  try {
    // 创建邮箱
    const mailbox = await createMailbox();
    console.log('创建邮箱:', mailbox);

    // 获取邮件
    const emails = await getEmails(mailbox.data.email);
    console.log('邮件列表:', emails);

    // 获取第一封邮件详情
    if (emails.data.emails.length > 0) {
      const emailDetail = await getEmailDetail(emails.data.emails[0].id);
      console.log('邮件详情:', emailDetail);
    }
  } catch (error) {
    console.error('API调用失败:', error);
  }
}
Python
使用requests库调用GoMail接口的完整示例
Python
import requests
import json

API_BASE = 'https://184772.xyz'
API_TOKEN = 'gm_your_token_here'

headers = {
    'Authorization': f'Bearer {API_TOKEN}',
    'Content-Type': 'application/json'
}

def create_mailbox(prefix='test', domain='184772.xyz'):
    """创建临时邮箱"""
    response = requests.post(
        f'{API_BASE}/api/external/mailbox',
        headers=headers,
        json={
            'prefix': prefix,
            'domain': domain
        }
    )
    return response.json()

def get_emails(email):
    """获取邮件列表"""
    response = requests.get(
        f'{API_BASE}/api/external/emails/{email}',
        headers=headers
    )
    return response.json()

def get_email_detail(email_id):
    """获取邮件详情"""
    response = requests.get(
        f'{API_BASE}/api/external/email/{email_id}',
        headers=headers
    )
    return response.json()

def download_attachment(attachment_id, filename):
    """下载附件"""
    response = requests.get(
        f'{API_BASE}/api/external/attachment/{attachment_id}',
        headers={'Authorization': f'Bearer {API_TOKEN}'}
    )

    if response.status_code == 200:
        with open(filename, 'wb') as f:
            f.write(response.content)
        return True
    return False

def get_token_info():
    """获取Token信息"""
    response = requests.get(
        f'{API_BASE}/api/external/mailbox',
        headers=headers
    )
    return response.json()

# 使用示例
if __name__ == '__main__':
    try:
        # 创建邮箱
        mailbox = create_mailbox()
        print('创建邮箱:', json.dumps(mailbox, indent=2, ensure_ascii=False))

        if mailbox['success']:
            email_address = mailbox['data']['email']

            # 获取邮件列表
            emails = get_emails(email_address)
            print('邮件列表:', json.dumps(emails, indent=2, ensure_ascii=False))

            # 如果有邮件,获取第一封邮件详情
            if emails['success'] and emails['data']['emails']:
                first_email = emails['data']['emails'][0]
                email_detail = get_email_detail(first_email['id'])
                print('邮件详情:', json.dumps(email_detail, indent=2, ensure_ascii=False))

                # 如果有附件,下载第一个附件
                if email_detail['success'] and email_detail['data']['attachments']:
                    attachment = email_detail['data']['attachments'][0]
                    success = download_attachment(attachment['id'], attachment['filename'])
                    print(f'附件下载: {"成功" if success else "失败"}')

        # 获取Token信息
        token_info = get_token_info()
        print('Token信息:', json.dumps(token_info, indent=2, ensure_ascii=False))

    except Exception as e:
        print(f'API调用失败: {e}')

📋 使用说明

API使用限制和最佳实践

🔒 使用限制
每个Token可设置使用次数限制
Token支持过期时间设置
临时邮箱24小时后自动过期
只有API调用消耗Token使用次数
✅ 最佳实践
妥善保存Token,避免泄露
定期检查Token使用情况
合理设置Token有效期
及时处理API错误响应
📞 技术支持
如果您在使用API过程中遇到问题,欢迎联系我们

技术支持邮箱:

3586177963@qq.com