{
"openapi": "3.0.3",
"info": {
"title": "Elektromail Admin API",
"version": "0.1"
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
},
"schemas": {
"StatusResponse": {
"type": "object",
"properties": { "status": { "type": "string" } },
"required": ["status"]
},
"ErrorResponse": {
"type": "object",
"properties": { "error": { "type": "string" } },
"required": ["error"]
},
"InjectRequest": {
"type": "object",
"properties": {
"user": { "type": "string" },
"mailbox": { "type": "string", "default": "INBOX" },
"raw": { "type": "string", "description": "Raw RFC822 message" }
},
"required": ["user", "raw"]
},
"InjectResponse": {
"type": "object",
"properties": { "uid": { "type": "integer", "format": "int32" } },
"required": ["uid"]
},
"CreateUserRequest": {
"type": "object",
"properties": {
"user": { "type": "string" },
"password": { "type": "string" },
"email": { "type": "string" }
},
"required": ["user", "password"]
},
"ConfigResponse": {
"type": "object",
"properties": {
"smtp_addr": { "type": "string" },
"imap_addr": { "type": "string" },
"http_addr": { "type": "string" },
"smtp_port": { "type": "integer", "format": "int32" },
"imap_port": { "type": "integer", "format": "int32" },
"http_port": { "type": "integer", "format": "int32" },
"smtp_enabled": { "type": "boolean" },
"imap_enabled": { "type": "boolean" },
"http_enabled": { "type": "boolean" },
"smtp_starttls": { "type": "boolean" },
"imap_starttls": { "type": "boolean" },
"storage": { "type": "string" },
"storage_path": { "type": "string" },
"http_token_required": { "type": "boolean" },
"auth_disabled": { "type": "boolean" },
"user_count": { "type": "integer" }
},
"required": [
"smtp_addr",
"imap_addr",
"http_addr",
"smtp_port",
"imap_port",
"http_port",
"smtp_enabled",
"imap_enabled",
"http_enabled",
"smtp_starttls",
"imap_starttls",
"storage",
"http_token_required",
"auth_disabled",
"user_count"
]
},
"Message": {
"type": "object",
"properties": {
"uid": { "type": "integer", "format": "int32" },
"size": { "type": "integer" },
"subject": { "type": "string" },
"from": { "type": "string" },
"raw": { "type": "string" }
},
"required": ["uid", "size", "subject", "from"]
},
"MessagesResponse": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": { "$ref": "#/components/schemas/Message" }
}
},
"required": ["messages"]
},
"MessageResponse": {
"type": "object",
"properties": {
"message": { "$ref": "#/components/schemas/Message" }
},
"required": ["message"]
},
"UsersResponse": {
"type": "object",
"properties": {
"users": { "type": "array", "items": { "type": "string" } }
},
"required": ["users"]
},
"UserEntry": {
"type": "object",
"properties": {
"user": { "type": "string" },
"email": { "type": "string" }
},
"required": ["user"]
},
"UsersDetailResponse": {
"type": "object",
"properties": {
"users": { "type": "array", "items": { "$ref": "#/components/schemas/UserEntry" } }
},
"required": ["users"]
}
}
},
"paths": {
"/reset": {
"post": {
"summary": "Clear all mailboxes and messages (restore baseline)",
"security": [{"bearerAuth": []}],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/StatusResponse" }
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
}
},
"/purge": {
"post": {
"summary": "Clear all messages but keep users and mailboxes",
"security": [{"bearerAuth": []}],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/StatusResponse" }
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
}
},
"/inject": {
"post": {
"summary": "Inject a raw RFC822 message",
"security": [{"bearerAuth": []}],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/InjectRequest" }
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/InjectResponse" }
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
}
},
"/users": {
"get": {
"summary": "List configured users",
"security": [{"bearerAuth": []}],
"parameters": [
{ "name": "include_email", "in": "query", "required": false, "schema": { "type": "boolean" } }
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{ "$ref": "#/components/schemas/UsersResponse" },
{ "$ref": "#/components/schemas/UsersDetailResponse" }
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
},
"post": {
"summary": "Create a user",
"security": [{"bearerAuth": []}],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/CreateUserRequest" }
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/StatusResponse" }
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
}
},
"/config": {
"get": {
"summary": "Configuration snapshot",
"security": [{"bearerAuth": []}],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ConfigResponse" }
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
}
},
"/messages": {
"get": {
"summary": "List messages for a user/mailbox",
"security": [{"bearerAuth": []}],
"parameters": [
{"name": "user", "in": "query", "required": true, "schema": { "type": "string" }},
{"name": "mailbox", "in": "query", "required": false, "schema": { "type": "string", "default": "INBOX" }},
{"name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }},
{"name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }},
{"name": "include_raw", "in": "query", "required": false, "schema": { "type": "boolean" }}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/MessagesResponse" }
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
},
"delete": {
"summary": "Delete a message by UID",
"security": [{"bearerAuth": []}],
"parameters": [
{"name": "user", "in": "query", "required": true, "schema": { "type": "string" }},
{"name": "mailbox", "in": "query", "required": false, "schema": { "type": "string", "default": "INBOX" }},
{"name": "uid", "in": "query", "required": true, "schema": { "type": "integer", "format": "int32" }}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/StatusResponse" }
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
}
},
"/messages/{uid}": {
"get": {
"summary": "Fetch a single message by UID",
"security": [{"bearerAuth": []}],
"parameters": [
{"name": "uid", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }},
{"name": "user", "in": "query", "required": true, "schema": { "type": "string" }},
{"name": "mailbox", "in": "query", "required": false, "schema": { "type": "string", "default": "INBOX" }},
{"name": "include_raw", "in": "query", "required": false, "schema": { "type": "boolean" }}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/MessageResponse" }
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
}
}
}
},
"/openapi.json": {
"get": {
"summary": "OpenAPI specification",
"security": [{"bearerAuth": []}],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": { "schema": { "type": "object" } }
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
}
}
}
}
},
"/docs": {
"get": {
"summary": "Swagger UI",
"security": [{"bearerAuth": []}],
"responses": {
"200": {
"description": "OK",
"content": {
"text/html": { "schema": { "type": "string" } }
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
}
}
}
}
}
}
}
