SirrChat Docs

한국어

English
简体中文
日本語
العربية

한국어

English
简体中文
日本語
العربية

Appearance

API 참조 ​

SirrChat은 프로그래밍 방식의 관리 및 통합을 위한 RESTful API를 제공합니다.

참고: API 기능은 현재 개발 중이며 일부 엔드포인트는 변경될 수 있습니다.

인증 ​

API 키 ​

인증을 위해 API 키를 사용합니다.

API 키 생성 ​

bash
sirrchatd api-key create --user admin@example.com

출력:

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": "user@example.com",
      "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": "newuser@example.com",
  "password": "securepassword",
  "quota": 5368709120,
  "blockchain_address": "0x742d..."
}

응답:

json
{
  "id": "user456",
  "email": "newuser@example.com",
  "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 등)
  • limit: 반환할 항목 수
  • offset: 오프셋

응답:

json
{
  "data": [
    {
      "uid": 12345,
      "from": "sender@example.com",
      "to": ["recipient@example.com"],
      "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

웹훅 ​

웹훅 구성 ​

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

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

웹훅 이벤트 ​

email.received ​

json
{
  "event": "email.received",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "user": "user@example.com",
    "from": "sender@example.com",
    "subject": "Email Subject",
    "size": 1024
  }
}

email.sent ​

json
{
  "event": "email.sent",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "user": "user@example.com",
    "to": ["recipient@example.com"],
    "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": "user1@example.com", "password": "pass1"},
      {"email": "user2@example.com", "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