مرجع API

يوفر SirrChat REST API للإدارة والتكامل البرمجي.

ملاحظة: وظائف API قيد التطوير حاليًا، وقد تتغير بعض نقاط النهاية.

المصادقة

مفاتيح API

استخدام مفاتيح API للمصادقة.

إنشاء مفتاح API

bash

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

الإخراج:

مفتاح API: mk_live_abc123def456ghi789
السر: 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، إلخ)
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

Webhooks

تكوين 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"
  }
}

SDKs

Go SDK

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}'

الوثائق ذات الصلة:

مرجع API ​

المصادقة ​

مفاتيح API ​

إنشاء مفتاح API ​

استخدام مفتاح API ​

نقاط النهاية ​

URL الأساسي ​

إدارة المستخدمين ​

قائمة المستخدمين ​

إنشاء مستخدم ​

الحصول على معلومات المستخدم ​

تحديث المستخدم ​

حذف مستخدم ​

إدارة النطاقات ​

قائمة النطاقات ​

إنشاء نطاق ​

حذف نطاق ​

إدارة الحصص ​

الحصول على استخدام الحصة ​

تعيين الحصة ​

إدارة البريد الإلكتروني ​

قائمة رسائل البريد الإلكتروني ​

الحصول على محتوى البريد الإلكتروني ​

حذف بريد إلكتروني ​

الإحصائيات ​

إحصائيات الخادم ​

إحصائيات المستخدم ​

Webhooks ​

تكوين Webhook ​

أحداث Webhook ​

email.received ​

email.sent ​

معالجة الأخطاء ​

تنسيق رد الخطأ ​

رموز الخطأ ​

تحديد المعدل ​

الترقيم ​

SDKs ​

Go SDK ​

Python SDK ​

JavaScript SDK ​

أمثلة ​

إنشاء مستخدمين بالدفعات ​

تصدير قائمة المستخدمين ​

مرجع API

المصادقة

مفاتيح API

إنشاء مفتاح API

استخدام مفتاح API

نقاط النهاية

URL الأساسي

إدارة المستخدمين

قائمة المستخدمين

إنشاء مستخدم

الحصول على معلومات المستخدم

تحديث المستخدم

حذف مستخدم

إدارة النطاقات

قائمة النطاقات

إنشاء نطاق

حذف نطاق

إدارة الحصص

الحصول على استخدام الحصة

تعيين الحصة

إدارة البريد الإلكتروني

قائمة رسائل البريد الإلكتروني

الحصول على محتوى البريد الإلكتروني

حذف بريد إلكتروني

الإحصائيات

إحصائيات الخادم

إحصائيات المستخدم

Webhooks

تكوين Webhook

أحداث Webhook

email.received

email.sent

معالجة الأخطاء

تنسيق رد الخطأ

رموز الخطأ

تحديد المعدل

الترقيم

SDKs

Go SDK

Python SDK

JavaScript SDK

أمثلة

إنشاء مستخدمين بالدفعات

تصدير قائمة المستخدمين