SirrChat Docs

简体中文

English
日本語
한국어
العربية

简体中文

English
日本語
한국어
العربية

Appearance

API 参考 ​

SirrChat 提供 RESTful API 用于程序化管理和集成。

注意: API 功能目前处于开发阶段，部分接口可能会有变化。

认证 ​

API 密钥 ​

使用 API 密钥进行认证。

创建 API 密钥 ​

bash
sirrchatd api-key create --user [email protected]

输出:

API Key: mk_live_abc123def456ghi789
Secret: sk_live_xyz789uvw456rst123

使用 API 密钥 ​

http
GET /api/v1/users HTTP/1.1
Host: mail.example.com:8080
Authorization: Bearer mk_live_abc123def456ghi789

端点 ​

基础 URL ​

https://mail.example.com:8080/api/v1

用户管理 ​

列出用户 ​

http
GET /api/v1/users

查询参数:

  • page: 页码 (默认 1)
  • limit: 每页数量 (默认 20)
  • domain: 按域名过滤

响应:

json
{
  "data": [
    {
      "id": "user123",
      "email": "[email protected]",
      "quota": 5368709120,
      "used": 1073741824,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

创建用户 ​

http
POST /api/v1/users
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "securepassword",
  "quota": 5368709120,
  "blockchain_address": "0x742d..."
}

响应:

json
{
  "id": "user456",
  "email": "[email protected]",
  "created_at": "2025-01-15T11:00:00Z"
}

获取用户信息 ​

http
GET /api/v1/users/{id}

更新用户 ​

http
PUT /api/v1/users/{id}
Content-Type: application/json

{
  "quota": 10737418240,
  "password": "newpassword"
}

删除用户 ​

http
DELETE /api/v1/users/{id}

域名管理 ​

列出域名 ​

http
GET /api/v1/domains

响应:

json
{
  "data": [
    {
      "id": "domain123",
      "name": "example.com",
      "users_count": 25,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

创建域名 ​

http
POST /api/v1/domains
Content-Type: application/json

{
  "name": "newdomain.com"
}

删除域名 ​

http
DELETE /api/v1/domains/{id}

配额管理 ​

获取配额使用 ​

http
GET /api/v1/users/{id}/quota

响应:

json
{
  "quota": 5368709120,
  "used": 1073741824,
  "percentage": 20.0,
  "files_count": 1234
}

设置配额 ​

http
PUT /api/v1/users/{id}/quota
Content-Type: application/json

{
  "quota": 10737418240
}

邮件管理 ​

列出邮件 ​

http
GET /api/v1/users/{id}/messages

查询参数:

  • mailbox: 邮箱名称 (INBOX, Sent, etc.)
  • limit: 返回数量
  • offset: 偏移量

响应:

json
{
  "data": [
    {
      "uid": 12345,
      "from": "[email protected]",
      "to": ["[email protected]"],
      "subject": "Test Email",
      "date": "2025-01-15T10:30:00Z",
      "size": 1024,
      "flags": ["\\Seen"]
    }
  ]
}

获取邮件内容 ​

http
GET /api/v1/users/{id}/messages/{uid}

删除邮件 ​

http
DELETE /api/v1/users/{id}/messages/{uid}

统计信息 ​

服务器统计 ​

http
GET /api/v1/stats

响应:

json
{
  "uptime": 172800,
  "users_total": 1234,
  "sessions_active": 42,
  "messages_today": 5678,
  "storage_used": 134678302720,
  "smtp": {
    "sent": 2345,
    "received": 3333,
    "rejected": 12
  },
  "imap": {
    "connections": 42,
    "commands": 12345
  }
}

用户统计 ​

http
GET /api/v1/users/{id}/stats

Webhook ​

配置 Webhook ​

http
POST /api/v1/webhooks
Content-Type: application/json

{
  "url": "https://example.com/webhook",
  "events": ["email.received", "email.sent"],
  "secret": "webhook_secret"
}

Webhook 事件 ​

email.received ​

json
{
  "event": "email.received",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "user": "[email protected]",
    "from": "[email protected]",
    "subject": "Email Subject",
    "size": 1024
  }
}

email.sent ​

json
{
  "event": "email.sent",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "user": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Email Subject"
  }
}

错误处理 ​

错误响应格式 ​

json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}

错误代码 ​

  • 400 Bad Request: 请求参数错误
  • 401 Unauthorized: 未授权
  • 403 Forbidden: 无权限
  • 404 Not Found: 资源不存在
  • 409 Conflict: 资源冲突
  • 429 Too Many Requests: 请求过多
  • 500 Internal Server Error: 服务器错误

速率限制 ​

API 请求受速率限制保护。

限制:

  • 认证用户: 1000 请求/小时
  • IP 地址: 100 请求/小时

响应头:

http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642179600

分页 ​

列表端点支持分页。

查询参数:

  • page: 页码 (从 1 开始)
  • limit: 每页数量 (最大 100)

响应:

json
{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "total_pages": 5
  },
  "links": {
    "first": "/api/v1/users?page=1",
    "last": "/api/v1/users?page=5",
    "prev": null,
    "next": "/api/v1/users?page=2"
  }
}

SDK ​

Go SDK ​

go
import "github.com/mail-chat-chain/mailchatd-go"

client := sirrchatd.NewClient("mk_live_abc123...")

user, err := client.Users.Get("user123")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("User: %s\n", user.Email)

Python SDK ​

python
from sirrchatd import Client

client = Client(api_key="mk_live_abc123...")

user = client.users.get("user123")
print(f"User: {user.email}")

JavaScript SDK ​

javascript
const SirrChatD = require('sirrchatd-js');

const client = new SirrChatD('mk_live_abc123...');

const user = await client.users.get('user123');
console.log(`User: ${user.email}`);

示例 ​

批量创建用户 ​

bash
curl -X POST https://mail.example.com:8080/api/v1/users/batch \
  -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {"email": "[email protected]", "password": "pass1"},
      {"email": "[email protected]", "password": "pass2"}
    ]
  }'

导出用户列表 ​

bash
curl -X GET "https://mail.example.com:8080/api/v1/users?limit=1000" \
  -H "Authorization: Bearer mk_live_abc123..." \
  | jq '.data[] | {email, quota, used}'

相关文档：

Released under the GPL 3.0 License.

Copyright © 2025 SirrChat Team