{
    "openapi": "3.0.3",
    "info": {
        "title": "ion.net.id Email API",
        "version": "1.0.0",
        "description": "Email read, reply, and send API. API key controls access, while CMS sends mailbox_password at request time for IMAP/SMTP authentication."
    },
    "servers": [
        {
            "url": "https://api.ion.net.id"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "API key"
            }
        },
        "schemas": {
            "Mailbox": {
                "type": "object",
                "properties": {
                    "email": {
                        "type": "string",
                        "example": "billing@ion.net.id"
                    },
                    "imap_host": {
                        "type": "string",
                        "example": "mail.ion.net.id"
                    },
                    "smtp_host": {
                        "type": "string",
                        "example": "mail.ion.net.id"
                    }
                }
            },
            "EmailSummary": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "12345"
                    },
                    "from": {
                        "type": "string",
                        "example": "Customer <customer@example.com>"
                    },
                    "to": {
                        "type": "string",
                        "example": "billing@ion.net.id"
                    },
                    "subject": {
                        "type": "string",
                        "example": "Konfirmasi pembayaran"
                    },
                    "date": {
                        "type": "string"
                    },
                    "message_id": {
                        "type": "string"
                    }
                }
            },
            "ReplyRequest": {
                "type": "object",
                "required": [
                    "mailbox_password",
                    "body"
                ],
                "properties": {
                    "mailbox_password": {
                        "type": "string",
                        "example": "password-email"
                    },
                    "body": {
                        "type": "string",
                        "example": "Terima kasih, pembayaran Anda sedang kami proses."
                    }
                }
            },
            "SendRequest": {
                "type": "object",
                "required": [
                    "mailbox_password",
                    "to",
                    "subject",
                    "body"
                ],
                "properties": {
                    "mailbox_password": {
                        "type": "string",
                        "example": "password-email"
                    },
                    "to": {
                        "type": "string",
                        "example": "customer@example.com"
                    },
                    "subject": {
                        "type": "string",
                        "example": "Informasi invoice"
                    },
                    "body": {
                        "type": "string",
                        "example": "Invoice Anda sudah kami terbitkan."
                    }
                }
            },
            "CreateMailboxRequest": {
                "type": "object",
                "required": [
                    "local_part",
                    "password"
                ],
                "properties": {
                    "local_part": {
                        "type": "string",
                        "example": "customer123"
                    },
                    "password": {
                        "type": "string",
                        "example": "StrongPassword123"
                    },
                    "real_name": {
                        "type": "string",
                        "example": "Customer 123"
                    },
                    "quota": {
                        "type": "string",
                        "example": "50M"
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    }
                }
            }
        }
    },
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/api/v1/mailboxes": {
            "get": {
                "summary": "List accessible mailboxes",
                "description": "Requires emails:read scope.",
                "responses": {
                    "200": {
                        "description": "Mailbox list"
                    },
                    "401": {
                        "description": "Unauthorized"
                    }
                }
            }
        },
        "/api/v1/mailboxes/{mailbox}/emails": {
            "get": {
                "summary": "List emails",
                "description": "Reads message headers from the mailbox via IMAP. Requires emails:read scope.",
                "parameters": [
                    {
                        "name": "mailbox",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "billing@ion.net.id"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 10,
                            "maximum": 50
                        }
                    },
                    {
                        "name": "unseen",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "X-Mailbox-Password",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Password mailbox email yang dikirim oleh CMS."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Email list"
                    },
                    "401": {
                        "description": "Mailbox authentication failed"
                    },
                    "422": {
                        "description": "Mailbox password required"
                    },
                    "502": {
                        "description": "Mail server error"
                    }
                }
            }
        },
        "/api/v1/mailboxes/{mailbox}/emails/{id}": {
            "get": {
                "summary": "Read email detail",
                "description": "Reads full raw email body from IMAP. Requires emails:read scope.",
                "parameters": [
                    {
                        "name": "mailbox",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "X-Mailbox-Password",
                        "in": "header",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Password mailbox email yang dikirim oleh CMS."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Email detail"
                    },
                    "401": {
                        "description": "Mailbox authentication failed"
                    },
                    "422": {
                        "description": "Mailbox password required"
                    },
                    "502": {
                        "description": "Mail server error"
                    }
                }
            }
        },
        "/api/v1/mailboxes/{mailbox}/emails/{id}/reply": {
            "post": {
                "summary": "Reply email using mailbox SMTP",
                "description": "Fetches original email context through IMAP and sends reply through SMTP using mailbox_password supplied by CMS. Requires emails:reply scope.",
                "parameters": [
                    {
                        "name": "mailbox",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ReplyRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Reply sent"
                    },
                    "401": {
                        "description": "Mailbox authentication failed"
                    },
                    "422": {
                        "description": "Invalid request"
                    },
                    "502": {
                        "description": "Mail server error"
                    }
                }
            }
        },
        "/api/v1/mailboxes/{mailbox}/send": {
            "post": {
                "summary": "Send new email using mailbox SMTP",
                "description": "Sends a new email through SMTP using mailbox_password supplied by CMS. Requires emails:send scope.",
                "parameters": [
                    {
                        "name": "mailbox",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SendRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Email sent"
                    },
                    "401": {
                        "description": "Mailbox authentication failed"
                    },
                    "422": {
                        "description": "Invalid request"
                    },
                    "502": {
                        "description": "Mail server error"
                    }
                }
            }
        },
        "/api/v1/domains/{domain}/mailboxes": {
            "post": {
                "summary": "Create mailbox in Virtualmin/Webmin",
                "description": "Creates a new mailbox user in the selected Virtualmin/Webmin domain. Requires mailboxes:create scope and domain permission.",
                "parameters": [
                    {
                        "name": "domain",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "kliniktech.com"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/CreateMailboxRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Mailbox created"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Domain not allowed or missing scope"
                    },
                    "409": {
                        "description": "Mailbox already exists"
                    },
                    "422": {
                        "description": "Invalid request"
                    },
                    "502": {
                        "description": "Virtualmin helper error"
                    }
                }
            }
        }
    }
}