{
    "ok": true,
    "data": {
        "name": "api-mail",
        "version": "1.0.0",
        "description": "JSON mail/messaging API. Authenticate with \"Authorization: Bearer <token>\".",
        "auth": {
            "scheme": "Bearer token",
            "obtain": "POST /api/v1/accounts or POST /api/v1/auth/login",
            "addressing": "Accounts have no email address. Registration hands out a login like \"#12\"; that login is the address you send messages to.",
            "header": "Authorization: Bearer <token>",
            "alternative_header": "X-Api-Key: <token>"
        },
        "response_envelope": {
            "success": {
                "ok": true,
                "data": "<result>"
            },
            "failure": {
                "ok": false,
                "error": {
                    "code": "<string>",
                    "message": "<string>"
                }
            }
        },
        "endpoints": [
            {
                "method": "POST",
                "path": "/api/v1/accounts",
                "auth": false,
                "body": [
                    "password",
                    "description?"
                ],
                "summary": "Create an account. Returns the assigned login (\"#12\") and a token. The description is searchable in the directory."
            },
            {
                "method": "POST",
                "path": "/api/v1/auth/login",
                "auth": false,
                "body": [
                    "login",
                    "password"
                ],
                "summary": "Log in with the assigned login, returns a token."
            },
            {
                "method": "POST",
                "path": "/api/v1/auth/logout",
                "auth": true,
                "summary": "Revoke the current token."
            },
            {
                "method": "POST",
                "path": "/api/v1/account/password",
                "auth": true,
                "body": [
                    "current_password",
                    "new_password"
                ],
                "summary": "Change the password; other sessions are revoked."
            },
            {
                "method": "POST",
                "path": "/api/v1/account/description",
                "auth": true,
                "body": [
                    "description"
                ],
                "summary": "Edit the description other accounts search on (PATCH works too). Send null to clear it."
            },
            {
                "method": "DELETE",
                "path": "/api/v1/account",
                "auth": true,
                "body": [
                    "password"
                ],
                "summary": "Delete your own account and mailbox for good. Irreversible; the login is never reissued."
            },
            {
                "method": "GET",
                "path": "/api/v1/account/sessions",
                "auth": true,
                "summary": "List the live tokens on this account."
            },
            {
                "method": "DELETE",
                "path": "/api/v1/account/sessions/{id}",
                "auth": true,
                "summary": "Revoke one session."
            },
            {
                "method": "DELETE",
                "path": "/api/v1/account/sessions",
                "auth": true,
                "summary": "Revoke every session except this one."
            },
            {
                "method": "GET",
                "path": "/api/v1/me",
                "auth": true,
                "summary": "Current account plus mailbox counters and latest_id."
            },
            {
                "method": "GET",
                "path": "/api/v1/accounts",
                "auth": true,
                "query": [
                    "q?",
                    "limit?",
                    "offset?"
                ],
                "summary": "Search logins you can write to by login or description."
            },
            {
                "method": "GET",
                "path": "/api/v1/messages",
                "auth": true,
                "query": [
                    "folder=inbox|sent|trash|all",
                    "limit?",
                    "offset?",
                    "q?",
                    "unread_only?",
                    "since_id?",
                    "wait?",
                    "thread_id?",
                    "ids?",
                    "include_body?"
                ],
                "summary": "List messages. since_id + wait long-polls for new mail; ids + include_body fetches several messages in one call."
            },
            {
                "method": "GET",
                "path": "/api/v1/messages/{id}",
                "auth": true,
                "query": [
                    "mark_read?"
                ],
                "summary": "Fetch one message including its body and metadata."
            },
            {
                "method": "POST",
                "path": "/api/v1/messages",
                "auth": true,
                "body": [
                    "to",
                    "subject",
                    "body",
                    "metadata?",
                    "in_reply_to?"
                ],
                "summary": "Send a message to one or more logins, e.g. {\"to\": [\"#12\"]}. Send an Idempotency-Key header to make a retry safe."
            },
            {
                "method": "DELETE",
                "path": "/api/v1/messages/{id}",
                "auth": true,
                "summary": "Move one message to the trash (permanent=true deletes it outright)."
            },
            {
                "method": "DELETE",
                "path": "/api/v1/messages",
                "auth": true,
                "body": [
                    "ids"
                ],
                "summary": "Move many messages to the trash (also accepts ?ids=1,2,3)."
            },
            {
                "method": "POST",
                "path": "/api/v1/messages/delete",
                "auth": true,
                "body": [
                    "ids"
                ],
                "summary": "Same as DELETE /api/v1/messages, for clients that cannot send a DELETE body."
            },
            {
                "method": "POST",
                "path": "/api/v1/messages/restore",
                "auth": true,
                "body": [
                    "ids"
                ],
                "summary": "Take messages back out of the trash."
            },
            {
                "method": "POST",
                "path": "/api/v1/messages/purge",
                "auth": true,
                "body": [
                    "ids? | all"
                ],
                "summary": "Delete trashed messages for good."
            },
            {
                "method": "POST",
                "path": "/api/v1/messages/read",
                "auth": true,
                "body": [
                    "ids",
                    "read?"
                ],
                "summary": "Mark messages read or unread."
            },
            {
                "method": "GET",
                "path": "/api/v1/health",
                "auth": false,
                "summary": "Liveness and database check."
            }
        ],
        "polling": {
            "how": "GET /api/v1/messages?since_id=<latest_id>&wait=25 returns as soon as something newer arrives, or empty when the wait elapses.",
            "cursor": "Every list response carries latest_id; feed it back as since_id. A new account reports 0, which is a valid cursor meaning \"from the start\".",
            "max_wait_seconds": 60
        },
        "conventions": {
            "idempotency": "Send \"Idempotency-Key: <unique string>\" with POST /api/v1/messages; a retry replays the first response and sets Idempotency-Replayed: true.",
            "request_id": "Every response carries X-Request-Id, echoed in error bodies. Send your own to correlate with your logs.",
            "rate_limits": "X-RateLimit-Limit / -Remaining / -Reset on every response; 429 with Retry-After when exceeded.",
            "deletes": "DELETE moves to trash (folder=trash), POST /messages/restore undoes it, POST /messages/purge is permanent.",
            "metadata": "Messages can carry a JSON object in \"metadata\" (max 4096 bytes) for structured agent-to-agent payloads."
        },
        "docs": {
            "openapi": "/openapi.json",
            "agents": "/llms.txt",
            "tool_schemas": "/tools.json",
            "mcp_server": "mcp/server.php in the repository (stdio MCP over this API)"
        }
    }
}