API Reference

SirrChat provides a RESTful API for programmatic management and integration.

Note: API functionality is currently in development, and some endpoints may change.

Authentication

API Keys

Use API keys for authentication.

Create API Key

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

Output:

API Key: mk_live_abc123def456ghi789
Secret: sk_live_xyz789uvw456rst123

Using API Key

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

Endpoints

Base URL

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

User Management

List Users

GET /api/v1/users

Query parameters:

• page: Page number (default 1)
• limit: Items per page (default 20)
• domain: Filter by domain

Response:

{
  "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
  }
}

Create User

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

{
  "email": "newuser@example.com",
  "password": "securepassword",
  "quota": 5368709120,
  "blockchain_address": "0x742d..."
}

Response:

{
  "id": "user456",
  "email": "newuser@example.com",
  "created_at": "2025-01-15T11:00:00Z"
}

Get User Information

GET /api/v1/users/{id}

Update User

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

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

Delete User

DELETE /api/v1/users/{id}

Domain Management

List Domains

GET /api/v1/domains

Response:

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

Create Domain

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

{
  "name": "newdomain.com"
}

Delete Domain

DELETE /api/v1/domains/{id}

Quota Management

Get Quota Usage

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

Response:

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

Set Quota

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

{
  "quota": 10737418240
}

Email Management

List Emails

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

Query parameters:

• mailbox: Mailbox name (INBOX, Sent, etc.)
• limit: Number of items to return
• offset: Offset

Response:

{
  "data": [
    {
      "uid": 12345,
      "from": "sender@example.com",
      "to": ["recipient@example.com"],
      "subject": "Test Email",
      "date": "2025-01-15T10:30:00Z",
      "size": 1024,
      "flags": ["\\Seen"]
    }
  ]
}

Get Email Content

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

Delete Email

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

Statistics

Server Statistics

GET /api/v1/stats

Response:

{
  "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
  }
}

User Statistics

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

Webhooks

Configure Webhook

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

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

Webhook Events

email.received

{
  "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

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

Error Handling

Error Response Format

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

Error Codes

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Unauthorized
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 409 Conflict: Resource conflict
• 429 Too Many Requests: Too many requests
• 500 Internal Server Error: Server error

Rate Limiting

API requests are protected by rate limiting.

Limits:

• Authenticated users: 1000 requests/hour
• IP address: 100 requests/hour

Response headers:

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

Pagination

List endpoints support pagination.

Query parameters:

• page: Page number (starts at 1)
• limit: Items per page (max 100)

Response:

{
  "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

from sirrchatd import Client

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

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

JavaScript SDK

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

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

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

Examples

Batch Create Users

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

Export User List

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

---

Related documentation:

• CLI Command Reference
• Configuration Guide
• GitHub - API Examples