{ "openapi": "3.0.0", "info": { "title": "Hostinger Mail API", "description": "# Overview\nThe Hostinger Mail API provides a set of endpoints that allow developers to manage Hostinger Email programmatically.\nThis API enables you to manage mailboxes and related resources tied to your Hostinger account.\n\nThe API is (mostly) RESTful and uses standard HTTP methods and status codes.\n\n# Official SDKs\nIntegrate the Hostinger Mail API in minutes using official, idiomatic SDKs - no more hand-rolling HTTP calls.\nPublished to native package managers, so it's a one-line install.\n\n- **PHP** - `composer require hostinger/mail-api-php-sdk` ([GitHub](https://github.com/hostinger/mail-api-php-sdk))\n- **TypeScript / Node.js** - `npm install hostinger-mail-api-sdk` ([GitHub](https://github.com/hostinger/mail-api-typescript-sdk))\n- **Python** - `pip install hostinger-mail-api` ([GitHub](https://github.com/hostinger/mail-api-python-sdk))\n- **CLI** - `brew install hostinger/tap/hostinger-mail` ([GitHub](https://github.com/hostinger/mail-api-cli))\n\n# AI agents (MCP)\nWant to read or send your email from Claude, Cursor, ChatGPT, or any other AI assistant? Hostinger ships an MCP (Model Context Protocol) server that wraps this API:\n\n```\nhttps://mcp.mail.hostinger.com/mcp\n```\n\nUse the same API token from the Hostinger Panel. Your agent only reaches what the token permits — order-scoped, optionally restricted to specific mailboxes within the order.\n\n
\nClaude Code (CLI)\n\n```bash\nclaude mcp add --scope user --transport http \\\n --header \"Authorization: Bearer YOUR_HOSTINGER_API_TOKEN\" \\\n -- hostinger-email https://mcp.mail.hostinger.com/mcp\n```\n\n
\n\n
\nClaude Desktop\n\nClaude Desktop connects to MCP servers via stdio. Use the `mcp-remote` bridge to talk to our HTTP server. Requires Node.js (`npx` ships with it).\n\nEdit the Claude Desktop config file. Path depends on your OS:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux:** `~/.config/Claude/claude_desktop_config.json`\n\nSet the contents to:\n\n```json\n{\n \"mcpServers\": {\n \"hostinger-email\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"mcp-remote\",\n \"https://mcp.mail.hostinger.com/mcp\",\n \"--header\",\n \"Authorization: Bearer YOUR_HOSTINGER_API_TOKEN\"\n ]\n }\n }\n}\n```\n\nQuit Claude Desktop fully (not just close the window) and reopen it. The connector icon should appear in the message composer.\n\nIf you have Claude Desktop's paid \"Custom Connectors\" feature, you can skip the `mcp-remote` bridge entirely and add the HTTP URL directly via the in-app UI:\n\n```json\n{\n \"mcpServers\": {\n \"hostinger-email\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.mail.hostinger.com/mcp\",\n \"headers\": { \"Authorization\": \"Bearer YOUR_HOSTINGER_API_TOKEN\" }\n }\n }\n}\n```\n\n
\n\n
\nCursor\n\nCreate or edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project root:\n\n```json\n{\n \"mcpServers\": {\n \"hostinger-email\": {\n \"url\": \"https://mcp.mail.hostinger.com/mcp\",\n \"headers\": { \"Authorization\": \"Bearer YOUR_HOSTINGER_API_TOKEN\" }\n }\n }\n}\n```\n\nRestart Cursor. The server is also configurable via `Cmd-Shift-P` → `View: Open MCP Settings` (newer Cursor versions).\n\n
\n\n
\nWhat can the agent do?\n\nSame as this REST API — read, search, send, move, flag, delete messages; list folders and mailboxes; manage webhooks. The agent calls these endpoints under the hood using your API token.\n\nThe agent only reaches what your token permits. Tokens are scoped to a single Hostinger order, and you can further restrict each token to specific mailboxes within that order when generating it in the Panel.\n\n
\n\n# Other plugins\n- **ChatGPT plugin** - read and send your Hostinger email straight from ChatGPT ([Open](https://chatgpt.com/plugins/plugin_asdk_app_6a323a8a890c819190480c9044395170))\n\n# Feedback from integrations and AI agents\nSomething did not work, was slow, or is missing? Tell the Hostinger mail team directly from your code or your agent: `POST /api/v1/mailboxes/{mailboxResourceId}/feedback` (MCP tool `email_report_feedback`) with a `score` (1-10) and a short `message`. Reports reach the team's feedback channel within minutes.\n\nReport when a call returned `4xx`/`5xx` or unexpected data, when a response was too slow, when documentation was missing or unclear, or when a capability you needed does not exist. Mention the failing operation and the status code you received so the team can find the request. Never include tokens, passwords or email contents: messages are scrubbed of secrets and capped at 2000 characters. Send one report per distinct issue.\n\n# Authentication\nThe API uses tokens for authentication. To authenticate your requests, you need to include a valid bearer token in the `Authorization` header of your HTTP requests:\n\n```yaml\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\nAPI tokens can be created and managed from the email provisioning tab in the Hostinger Panel.\nTokens are scoped to a single order; their permissions are limited to that order.\n\nOnly mailboxes belonging to the order can be accessed and managed by an API token.\n\n# Rate Limiting\nTo ensure fair usage and prevent abuse, the API enforces rate limits on the number of requests that can be made within a certain time period.\nIf you exceed the rate limit, you will receive a `429 Too Many Requests` response.\nYour IP address might get temporarily blocked if you exceed the rate limit multiple times.\n\n# Parameters\nAll requests sent to the API must have the content type `application/json`.\n`POST`, `PUT`, `PATCH` methods may include a JSON object in the request body.\nDocumentation provides the required structure and examples of the object.\nSome endpoints require path parameters.\nThese parameters are included in the URL path and are marked with curly braces.\n\n# Response envelope\nAll non-`204` responses wrap the payload in a top-level `data` field.\n\nSingle resource:\n\n```json\n{\n \"data\": {\n \"resourceId\": \"AC1a2b3c4d5e6f7g\",\n \"address\": \"user@example.com\"\n }\n}\n```\n\nCollection (empty or otherwise):\n\n```json\n{\n \"data\": []\n}\n```\n\n# Pagination\nPaginated responses include a top-level `pagination` object alongside `data`. By default, the API returns 50 items per page.\nThe page number can be specified using the `page` query parameter, for example: `/core/v1/public/mailboxes?page=2`.\n\n```json\n{\n \"data\": [],\n \"pagination\": {\n \"page\": 1,\n \"perPage\": 25,\n \"total\": 137,\n \"totalPages\": 6\n }\n}\n```\n\n# Errors\nAll `4xx` and `5xx` responses share a single envelope. Always parse `code` for programmatic handling; `error` is a human-readable message intended for logs and support tickets.\n\n```json\n{\n \"error\": \"Mailbox not found.\",\n \"code\": \"ERR_MAILBOX_NOT_FOUND\",\n \"params\": {}\n}\n```", "version": "1.2.2" }, "servers": [ { "url": "https://api.mail.hostinger.com" } ], "paths": { "/api/v1/mailboxes/{mailboxResourceId}/feedback": { "post": { "tags": [ "Feedback" ], "summary": "Submit feedback", "description": "Send the user's feedback about the Hostinger Email API to the Hostinger mail team.\n\nOnly call this when the user explicitly asks to send feedback, report a problem, or request a feature. Send the user's own words; never include tokens, passwords or email contents. The message is capped at 2000 characters.\n\nA `429` (`ERR_FEEDBACK_RATE_LIMIT`) means feedback for this customer was submitted less than ten seconds ago; wait and retry.", "operationId": "submitFeedback", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the feedback is about, as returned by `GET /api/v1/me`.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Feedback.SubmitRequest" } } } }, "responses": { "204": { "description": "Feedback accepted." }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "429": { "$ref": "#/components/responses/Common.Response.TooManyRequestsResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" }, "504": { "$ref": "#/components/responses/Common.Response.GatewayTimeoutResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages": { "get": { "tags": [ "Messages" ], "summary": "List messages", "description": "List messages in a folder. Use POST /search for filtering. Sort fields: uid, date, size (prefix with `-` for descending). Default `-uid`.", "operationId": "listMessages", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" }, { "name": "page", "in": "query", "description": "Page number (1-based).", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Items per page (max 100).", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "Sort field with optional `-` prefix for descending. Allowed: uid, date, size.", "required": false, "schema": { "type": "string", "default": "-uid" } } ], "responses": { "200": { "description": "Paginated list of messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.Collection" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Messages" ], "summary": "Delete all messages", "description": "Permanently delete every message in a folder (empty the folder).", "operationId": "deleteAllMessages", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX.Trash" } ], "responses": { "204": { "description": "Messages deleted successfully." }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/{uid}": { "get": { "tags": [ "Messages" ], "summary": "Get message", "description": "Retrieve a single message by UID.", "operationId": "getMessage", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" }, { "name": "uid", "in": "path", "description": "Message UID.", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 42 } ], "responses": { "200": { "description": "Message payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.Resource" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Messages" ], "summary": "Delete message", "description": "Permanently delete a single message.", "operationId": "deleteMessage", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" }, { "name": "uid", "in": "path", "description": "Message UID.", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 42 } ], "responses": { "204": { "description": "Message deleted successfully." }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Messages" ], "summary": "Update message flags", "description": "Add and/or remove flags on a single message. Returns the updated message.", "operationId": "patchMessage", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" }, { "name": "uid", "in": "path", "description": "Message UID.", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 42 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.FlagsRequest" } } } }, "responses": { "200": { "description": "Updated message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.Resource" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/delete": { "post": { "tags": [ "Messages" ], "summary": "Delete messages", "description": "Permanently delete multiple messages from a folder.", "operationId": "deleteMessages", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.DeleteBulkRequest" } } } }, "responses": { "204": { "description": "Messages deleted successfully." }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/{uid}/attachments/{attachmentId}": { "get": { "tags": [ "Messages" ], "summary": "Download message attachment", "description": "Download a message attachment as `application/octet-stream`.", "operationId": "getMessageAttachment", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" }, { "name": "uid", "in": "path", "description": "Message UID.", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 42 }, { "name": "attachmentId", "in": "path", "description": "Attachment ID (opaque, returned by GET message).", "required": true, "schema": { "type": "string" }, "example": "YXR0YWNobWVudDpJTkJPWDoxMjM6MS4y" } ], "responses": { "200": { "description": "Decoded attachment body.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/{uid}/source": { "get": { "tags": [ "Messages" ], "summary": "Get message source", "description": "Retrieve raw RFC822 source of a message as `message/rfc822` attachment.", "operationId": "getMessageSource", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" }, { "name": "uid", "in": "path", "description": "Message UID.", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 42 } ], "responses": { "200": { "description": "Raw RFC822 source.", "content": { "message/rfc822": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/{uid}/text": { "get": { "tags": [ "Messages" ], "summary": "Get message text content", "description": "Retrieve rendered text (plain + HTML) of a message. Marks message as `\\Seen`.", "operationId": "getMessageText", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" }, { "name": "uid", "in": "path", "description": "Message UID.", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 42 } ], "responses": { "200": { "description": "Rendered text and HTML payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.MessageTextResource" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ], "x-mcp": { "readOnlyHint": false } } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/{uid}/move": { "post": { "tags": [ "Messages" ], "summary": "Move message", "description": "Move a single message to a target folder.", "operationId": "moveMessage", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Source folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" }, { "name": "uid", "in": "path", "description": "Message UID.", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 42 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.MoveRequest" } } } }, "responses": { "204": { "description": "Message moved successfully." }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/move": { "post": { "tags": [ "Messages" ], "summary": "Move messages", "description": "Move multiple messages from a source folder to a target folder.", "operationId": "moveMessages", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Source folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.MoveBulkRequest" } } } }, "responses": { "204": { "description": "Messages moved successfully." }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/search": { "post": { "tags": [ "Messages" ], "summary": "Search messages", "description": "Search messages in a folder. Filters in body; pagination and sort via query (`page`, `perPage`, `sort`).", "operationId": "searchMessages", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" }, { "name": "page", "in": "query", "description": "Page number (1-based).", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Items per page (max 100).", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "Sort field with optional `-` prefix for descending. Allowed: uid, date, size.", "required": false, "schema": { "type": "string", "default": "-uid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.SearchRequest" } } } }, "responses": { "200": { "description": "Paginated list of matching messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.Collection" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}/messages/flags": { "post": { "tags": [ "Messages" ], "summary": "Update flags on multiple messages", "description": "Add and/or remove flags on multiple messages. Returns 200 when all UIDs succeed, 207 with per-UID outcome when some fail.", "operationId": "updateMessageFlags", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.FlagsBulkRequest" } } } }, "responses": { "200": { "description": "All UIDs updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.UpdateFlagsResult" } } } }, "207": { "description": "Some UIDs failed; see body for per-UID outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.FolderMessages.UpdateFlagsResult" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders": { "get": { "tags": [ "Folders" ], "summary": "List folders", "description": "Retrieve a paginated list of folders in the managed mailbox.", "operationId": "listFolders", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "page", "in": "query", "description": "Page number (1-based).", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Items per page (max 100).", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of folders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Folders.Collection" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "Folders" ], "summary": "Create folder", "description": "Create a new folder in the managed mailbox.", "operationId": "createFolder", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Folders.CreateRequest" } } } }, "responses": { "201": { "description": "Folder created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Folders.Resource" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "409": { "$ref": "#/components/responses/Common.Response.ConflictResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/folders/{folder}": { "put": { "tags": [ "Folders" ], "summary": "Update folder", "description": "Rename an existing folder.", "operationId": "updateFolder", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Current folder path (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX.OldName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Folders.UpdateRequest" } } } }, "responses": { "200": { "description": "Folder renamed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Folders.Resource" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "409": { "$ref": "#/components/responses/Common.Response.ConflictResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Folders" ], "summary": "Delete folder", "description": "Delete a folder and all of its subfolders.", "operationId": "deleteFolder", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "folder", "in": "path", "description": "Folder path to delete (URL-encoded).", "required": true, "schema": { "type": "string" }, "example": "INBOX.OldName" } ], "responses": { "204": { "description": "Folder and all subfolders deleted." }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "409": { "$ref": "#/components/responses/Common.Response.ConflictResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/me": { "get": { "tags": [ "Account" ], "summary": "Get the authenticated account", "description": "Returns the authenticated account and the mailboxes it can manage.", "operationId": "getCurrentAccount", "responses": { "200": { "description": "Authenticated account with the mailboxes the API key can manage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Me.Resource" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/quota": { "get": { "tags": [ "Quota" ], "summary": "Get mailbox quota", "description": "Retrieve storage and message quota usage for the managed mailbox.", "operationId": "getQuota", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" } ], "responses": { "200": { "description": "Mailbox quota usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Quota.Resource" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/send": { "post": { "tags": [ "Send" ], "summary": "Send email", "description": "Send a message from the managed mailbox. Saves a copy to INBOX.Sent.", "operationId": "sendEmail", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Send.Request" } } } }, "responses": { "204": { "description": "Message sent and saved to sent folder." }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" }, "504": { "$ref": "#/components/responses/Common.Response.GatewayTimeoutResponse" } }, "security": [ { "BearerAuth": [] } ], "x-mcp": { "openWorldHint": true } } }, "/api/v1/mailboxes/{mailboxResourceId}/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "List webhooks for a mailbox.", "operationId": "listWebhooks", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "status", "in": "query", "description": "Return only webhooks with this status.", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "disabled" ] } }, { "name": "page", "in": "query", "description": "Page number (1-based).", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Items per page (max 1000).", "required": false, "schema": { "type": "integer", "default": 15, "maximum": 1000, "minimum": 1 } } ], "responses": { "200": { "description": "Paginated list of webhooks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Webhooks.Collection" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook", "description": "Create a webhook. The response includes the one-time `secret` — store it securely as it is never returned again.", "operationId": "createWebhook", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox the bearer token is authorized for.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Webhooks.CreateRequest" } } } }, "responses": { "201": { "description": "Webhook created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Webhooks.ResourceWithSecret" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ], "x-mcp": { "openWorldHint": true } } }, "/api/v1/mailboxes/{mailboxResourceId}/webhooks/{webhook}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook", "description": "Retrieve a single webhook by id.", "operationId": "getWebhook", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "webhook", "in": "path", "description": "Webhook identifier (UUID v7).", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "019683f8-1234-7abc-8def-0123456789ab" } ], "responses": { "200": { "description": "Webhook payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Webhooks.Resource" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook", "description": "Delete a webhook.", "operationId": "deleteWebhook", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "webhook", "in": "path", "description": "Webhook identifier (UUID v7).", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "019683f8-1234-7abc-8def-0123456789ab" } ], "responses": { "204": { "description": "Webhook deleted." }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook", "description": "Partially update a webhook.", "operationId": "updateWebhook", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "webhook", "in": "path", "description": "Webhook identifier (UUID v7).", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "019683f8-1234-7abc-8def-0123456789ab" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Webhooks.UpdateRequest" } } } }, "responses": { "200": { "description": "Updated webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Webhooks.Resource" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "422": { "$ref": "#/components/responses/Common.Response.ValidationFailedResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ], "x-mcp": { "openWorldHint": true } } }, "/api/v1/mailboxes/{mailboxResourceId}/webhooks/{webhook}/regenerate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Regenerate webhook secret", "description": "Regenerate the webhook secret. The previous secret is immediately invalidated. The new secret is returned once.", "operationId": "regenerateWebhookSecret", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "webhook", "in": "path", "description": "Webhook identifier (UUID v7).", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "019683f8-1234-7abc-8def-0123456789ab" } ], "responses": { "200": { "description": "Webhook with new secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Webhooks.ResourceWithSecret" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/mailboxes/{mailboxResourceId}/webhooks/{webhook}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Test webhook", "description": "Send a test delivery to the webhook URL and return the upstream response.", "operationId": "testWebhook", "parameters": [ { "name": "mailboxResourceId", "in": "path", "description": "Resource ID of the managed mailbox.", "required": true, "schema": { "type": "string" }, "example": "AC1a2b3c4d5e6f7g" }, { "name": "webhook", "in": "path", "description": "Webhook identifier (UUID v7).", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "019683f8-1234-7abc-8def-0123456789ab" } ], "responses": { "200": { "description": "Test delivery result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1.Webhooks.TestResult" } } } }, "401": { "$ref": "#/components/responses/Common.Response.UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/Common.Response.ForbiddenResponse" }, "404": { "$ref": "#/components/responses/Common.Response.NotFoundResponse" }, "500": { "$ref": "#/components/responses/Common.Response.InternalServerErrorResponse" }, "502": { "$ref": "#/components/responses/Common.Response.BadGatewayResponse" } }, "security": [ { "BearerAuth": [] } ], "x-mcp": { "openWorldHint": true } } } }, "components": { "schemas": { "Error": { "description": "Standard error envelope. Frontend translations key off `code`, never off `error`.", "required": [ "error", "code" ], "properties": { "error": { "description": "Human-readable error message.", "type": "string", "example": "Resource not found." }, "code": { "description": "Machine-readable error code in SCREAMING_SNAKE_CASE.", "type": "string", "example": "ERR_RESOURCE_NOT_FOUND" }, "params": { "description": "Additional structured context for the error. May be omitted.", "type": "object", "additionalProperties": {} } }, "type": "object" }, "Pagination": { "description": "Pagination metadata for paginated collections.", "required": [ "page", "perPage", "total", "totalPages" ], "properties": { "page": { "description": "Current page number (1-based).", "type": "integer", "example": 1 }, "perPage": { "description": "Items per page.", "type": "integer", "example": 25 }, "total": { "description": "Total number of items across all pages.", "type": "integer", "example": 137 }, "totalPages": { "description": "Total number of pages.", "type": "integer", "example": 6 } }, "type": "object" }, "V1.Feedback.SubmitRequest": { "description": "Feedback the user wants to send to the Hostinger mail team. The message is scrubbed of tokens, JWTs and key/secret/password values before validation and storage, so the length limit applies to the scrubbed text.", "required": [ "score", "message" ], "properties": { "score": { "description": "The user's rating of the Hostinger Email API: 1 (poor) to 10 (excellent).", "type": "integer", "example": 3, "maximum": 10, "minimum": 1 }, "message": { "description": "The user's feedback in their own words. Never include tokens, passwords or email contents.", "type": "string", "example": "Sending a message with a 10 MB attachment fails with a timeout.", "maxLength": 2000 } }, "type": "object" }, "V1.FolderMessages.Collection": { "description": "Paginated list of messages.", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1.FolderMessages.Message" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" }, "V1.FolderMessages.DeleteBulkRequest": { "description": "Body for permanently deleting multiple messages.", "required": [ "uids" ], "properties": { "uids": { "description": "Message UIDs to delete. 1-100 entries, each > 0.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 42, 43, 44 ], "maxItems": 100, "minItems": 1 } }, "type": "object" }, "V1.FolderMessages.FlagsBulkRequest": { "description": "Add and/or remove flags on multiple messages. At least one of addFlags or removeFlags must be set.", "required": [ "uids" ], "properties": { "uids": { "description": "Message UIDs to update. 1-100 entries, each > 0.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 42, 43, 44 ], "maxItems": 100, "minItems": 1 }, "addFlags": { "description": "IMAP flags to set on every listed message, e.g. \\Seen, \\Flagged, \\Answered, $forwarded.", "type": "array", "items": { "type": "string", "example": "\\Seen", "maxLength": 255, "minLength": 1 }, "example": [ "\\Seen", "\\Flagged", "$forwarded" ] }, "removeFlags": { "description": "IMAP flags to clear from every listed message.", "type": "array", "items": { "type": "string", "example": "\\Seen", "maxLength": 255, "minLength": 1 }, "example": [ "\\Seen" ] } }, "type": "object" }, "V1.FolderMessages.FlagsRequest": { "description": "Add and/or remove flags on a message. At least one of addFlags or removeFlags must be set.", "properties": { "addFlags": { "description": "IMAP flags to set on the message, e.g. \\Seen, \\Flagged, \\Answered, $forwarded.", "type": "array", "items": { "type": "string", "example": "\\Seen", "maxLength": 255, "minLength": 1 }, "example": [ "\\Seen", "\\Flagged", "$forwarded" ] }, "removeFlags": { "description": "IMAP flags to clear from the message.", "type": "array", "items": { "type": "string", "example": "\\Seen", "maxLength": 255, "minLength": 1 }, "example": [ "\\Seen" ] } }, "type": "object" }, "V1.FolderMessages.Message": { "description": "A message in a folder of the managed mailbox.", "required": [ "uid", "path", "date", "flags", "unseen", "size", "subject", "from", "to", "cc", "bcc", "messageId", "inReplyTo", "attachments" ], "properties": { "uid": { "type": "integer", "example": 123 }, "path": { "type": "string", "example": "INBOX" }, "date": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" }, "flags": { "type": "array", "items": { "type": "string", "example": "\\Seen" }, "example": [ "\\Seen", "\\Flagged" ] }, "unseen": { "type": "boolean", "example": false }, "size": { "type": "integer", "example": 2048 }, "subject": { "type": "string", "example": "Test Email Subject", "nullable": true }, "from": { "oneOf": [ { "$ref": "#/components/schemas/V1.FolderMessages.MessageAddress" } ], "nullable": true }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/V1.FolderMessages.MessageAddress" } }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/V1.FolderMessages.MessageAddress" } }, "bcc": { "type": "array", "items": { "$ref": "#/components/schemas/V1.FolderMessages.MessageAddress" } }, "messageId": { "type": "string", "example": "<1234567890@example.com>", "nullable": true }, "inReplyTo": { "type": "string", "example": "<0987654321@example.com>", "nullable": true }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/V1.FolderMessages.MessageAttachment" } } }, "type": "object" }, "V1.FolderMessages.MessageAddress": { "description": "A single email address with optional display name.", "required": [ "name", "address" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "address": { "type": "string", "example": "john@example.com" } }, "type": "object" }, "V1.FolderMessages.MessageAttachment": { "description": "Attachment metadata attached to a message.", "required": [ "id", "contentType", "sizeBytes", "inline", "filename", "contentId" ], "properties": { "id": { "description": "Opaque attachment identifier. Use as the {attachmentId} path parameter on the download endpoint.", "type": "string", "example": "YXR0YWNobWVudDpJTkJPWDoxMjM6MS4y" }, "contentType": { "type": "string", "example": "application/pdf" }, "sizeBytes": { "type": "integer", "example": 1024 }, "inline": { "type": "boolean", "example": false }, "filename": { "type": "string", "example": "document.pdf", "nullable": true }, "contentId": { "type": "string", "example": "", "nullable": true } }, "type": "object" }, "V1.FolderMessages.MessageText": { "description": "Rendered text and HTML parts of a message.", "required": [ "text", "html" ], "properties": { "text": { "type": "string", "example": "Hello world" }, "html": { "type": "string", "example": "

Hello world

" } }, "type": "object" }, "V1.FolderMessages.MessageTextResource": { "description": "Single message text payload.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/V1.FolderMessages.MessageText" } }, "type": "object" }, "V1.FolderMessages.MoveBulkRequest": { "description": "Body for moving multiple messages to a target folder.", "required": [ "uids", "targetFolder" ], "properties": { "uids": { "description": "Message UIDs to move. 1-100 entries, each > 0.", "type": "array", "items": { "type": "integer", "minimum": 1 }, "example": [ 42, 43, 44 ], "maxItems": 100, "minItems": 1 }, "targetFolder": { "description": "Destination folder path.", "type": "string", "example": "INBOX.Sent", "maxLength": 100, "minLength": 1 } }, "type": "object" }, "V1.FolderMessages.MoveRequest": { "description": "Body for moving a single message to a target folder.", "required": [ "targetFolder" ], "properties": { "targetFolder": { "description": "Destination folder path.", "type": "string", "example": "INBOX.Sent", "maxLength": 100, "minLength": 1 } }, "type": "object" }, "V1.FolderMessages.Resource": { "description": "Single message payload.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/V1.FolderMessages.Message" } }, "type": "object" }, "V1.FolderMessages.SearchRequest": { "description": "Search criteria. All fields optional. subject, from, to, cc and body are alternatives (a message matching any one of them qualifies); all other fields are combined with AND.", "properties": { "since": { "description": "Only messages received on or after this date (YYYY-MM-DD).", "type": "string", "format": "date", "example": "2024-01-01" }, "before": { "description": "Only messages received before this date (YYYY-MM-DD).", "type": "string", "format": "date", "example": "2024-12-31" }, "flags": { "description": "Only messages carrying all of these IMAP flags, e.g. \\Seen, \\Flagged, \\Answered, $forwarded.", "type": "array", "items": { "type": "string", "example": "\\Seen", "maxLength": 255, "minLength": 1 }, "example": [ "\\Seen", "\\Flagged" ] }, "uid": { "description": "IMAP UID set: single UID, range (1:100), open range (100:*), or comma-separated list.", "type": "string", "example": "1:100" }, "subject": { "description": "Case-insensitive substring match on the Subject header. OR-combined with from/to/cc/body.", "type": "string", "example": "meeting", "maxLength": 1024 }, "from": { "description": "Case-insensitive substring match on the From header. OR-combined with subject/to/cc/body.", "type": "string", "example": "john@example.com", "maxLength": 320 }, "to": { "description": "Case-insensitive substring match on the To header. OR-combined with subject/from/cc/body.", "type": "string", "example": "jane@example.com", "maxLength": 320 }, "cc": { "description": "Case-insensitive substring match on the Cc header. OR-combined with subject/from/to/body.", "type": "string", "example": "team@example.com", "maxLength": 320 }, "body": { "description": "Case-insensitive substring match on the message body only (headers excluded). OR-combined with subject/from/to/cc.", "type": "string", "example": "important", "maxLength": 1024 }, "header": { "description": "Match a specific header as Name:value, e.g. X-Custom-Header:value. Value match is a substring.", "type": "string", "example": "X-Custom-Header:value", "maxLength": 1024 }, "larger": { "description": "Only messages larger than this size in bytes.", "type": "integer", "example": 1024, "minimum": 0 }, "smaller": { "description": "Only messages smaller than this size in bytes.", "type": "integer", "example": 1048576, "minimum": 0 }, "text": { "description": "Case-insensitive substring match across headers and body.", "type": "string", "example": "urgent", "maxLength": 1024 } }, "type": "object" }, "V1.FolderMessages.UpdateFlagsResult": { "description": "Per-UID outcome of a bulk flag update. 200 when every UID succeeded, 207 when at least one failed.", "required": [ "data" ], "properties": { "data": { "required": [ "successful", "failed" ], "properties": { "successful": { "type": "array", "items": { "type": "integer" }, "example": [ 42, 43 ] }, "failed": { "type": "array", "items": { "required": [ "uid", "reason" ], "properties": { "uid": { "type": "integer", "example": 44 }, "reason": { "type": "string", "example": "Failed to update message flags" } }, "type": "object" } } }, "type": "object" } }, "type": "object" }, "V1.Folders.Collection": { "description": "Paginated list of folders.", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1.Folders.Folder" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" }, "V1.Folders.CreateRequest": { "description": "Body for creating a folder.", "required": [ "name" ], "properties": { "name": { "description": "Folder name. Length 1-100 after trimming.", "type": "string", "example": "Projects", "maxLength": 100, "minLength": 1 } }, "type": "object" }, "V1.Folders.Folder": { "description": "A folder (IMAP mailbox) in the managed mailbox.", "required": [ "path", "name", "delimiter", "specialUse", "messageCount", "unreadCount" ], "properties": { "path": { "description": "Full hierarchical folder path including the delimiter.", "type": "string", "example": "INBOX.Sent" }, "name": { "description": "Leaf name of the folder.", "type": "string", "example": "Sent" }, "delimiter": { "description": "Hierarchy delimiter used by the IMAP server.", "type": "string", "example": "." }, "specialUse": { "description": "IMAP SPECIAL-USE attribute (RFC 6154). `null` for regular folders.", "type": "string", "example": "\\Sent", "nullable": true }, "messageCount": { "description": "Total number of messages in the folder.", "type": "integer", "example": 42 }, "unreadCount": { "description": "Number of unread messages in the folder.", "type": "integer", "example": 5 } }, "type": "object" }, "V1.Folders.Resource": { "description": "Single folder payload.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/V1.Folders.Folder" } }, "type": "object" }, "V1.Folders.UpdateRequest": { "description": "Body for renaming a folder.", "required": [ "name" ], "properties": { "name": { "description": "New folder name. Length 1-100 after trimming.", "type": "string", "example": "Archive", "maxLength": 100, "minLength": 1 } }, "type": "object" }, "V1.Me.Mailbox": { "description": "A mailbox the authenticated API token can manage.", "required": [ "resourceId", "address" ], "properties": { "resourceId": { "description": "Unique identifier of the mailbox.", "type": "string", "pattern": "^AC[A-Za-z0-9]+$", "example": "AC1a2b3c4d5e6f7g" }, "address": { "description": "Email address of the mailbox.", "type": "string", "format": "email", "example": "user@example.com" } }, "type": "object" }, "V1.Me.Resource": { "description": "Authenticated account payload.", "required": [ "data" ], "properties": { "data": { "required": [ "orderResourceId", "mailboxes" ], "properties": { "orderResourceId": { "description": "Identifier of the order this API token is scoped to.", "type": "string", "pattern": "^OR[A-Za-z0-9]+$", "example": "OR1a2b3c4d5e6f7g" }, "mailboxes": { "description": "Mailboxes that the authenticated API token can manage.", "type": "array", "items": { "$ref": "#/components/schemas/V1.Me.Mailbox" } } }, "type": "object" } }, "type": "object" }, "V1.Quota.Quota": { "description": "Storage and message quota usage for the managed mailbox.", "required": [ "quotas", "totalUsage", "totalLimit", "totalPercentage", "supported" ], "properties": { "quotas": { "description": "Per-resource quota breakdown reported by the IMAP server.", "type": "array", "items": { "$ref": "#/components/schemas/V1.Quota.QuotaResource" } }, "totalUsage": { "description": "Aggregate storage usage across all resources, in bytes.", "type": "integer", "example": 1048576 }, "totalLimit": { "description": "Aggregate storage limit across all resources, in bytes.", "type": "integer", "example": 1073741824 }, "totalPercentage": { "description": "Aggregate storage usage as a percentage of the total limit.", "type": "integer", "example": 0 }, "supported": { "description": "Whether the IMAP server reports quota information for this mailbox.", "type": "boolean", "example": true } }, "type": "object" }, "V1.Quota.QuotaResource": { "description": "Usage and limit for a single IMAP quota resource.", "required": [ "resourceName", "usage", "limit", "percentage" ], "properties": { "resourceName": { "description": "Name of the quota resource as reported by the IMAP server.", "type": "string", "example": "STORAGE" }, "usage": { "description": "Current usage of the resource (bytes for STORAGE, count for MESSAGE).", "type": "integer", "example": 1048576 }, "limit": { "description": "Maximum allowed value for the resource (bytes for STORAGE, count for MESSAGE).", "type": "integer", "example": 1073741824 }, "percentage": { "description": "Usage as a percentage of the limit.", "type": "integer", "example": 0 } }, "type": "object" }, "V1.Quota.Resource": { "description": "Mailbox quota payload.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/V1.Quota.Quota" } }, "type": "object" }, "V1.Send.MessageRef": { "description": "Reference to a source message by UID within a folder, used for reply/forward threading. Both fields are required.", "required": [ "uid", "folder" ], "properties": { "uid": { "description": "UID of the source message.", "type": "integer", "example": 123 }, "folder": { "description": "Folder containing the source message.", "type": "string", "example": "INBOX" } }, "type": "object" }, "V1.Send.Attachment": { "description": "Attachment payload for outgoing mail. Supports regular attachments and inline images linked via Content-ID.", "required": [ "filename", "content" ], "properties": { "filename": { "description": "File name shown to the recipient, including extension.", "type": "string", "example": "invoice.pdf" }, "content": { "description": "Attachment body. Base64-encoded by default; set encoding to switch.", "type": "string", "example": "JVBERi0xLjQK..." }, "contentType": { "description": "MIME type of the attachment, e.g. application/pdf. Not inferred from filename; set it explicitly so clients render the attachment correctly.", "type": "string", "example": "application/pdf" }, "cid": { "description": "Content-ID for inline images. Reference from HTML as .", "type": "string", "example": "logo" }, "encoding": { "description": "Encoding of content. Defaults to base64.", "type": "string", "example": "base64" } }, "type": "object" }, "V1.Send.Request": { "description": "Outgoing message payload. At least one of to, cc, or bcc must be present.", "properties": { "to": { "description": "Primary recipient email addresses.", "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "recipient@example.com" ] }, "displayName": { "description": "Sender display name shown in the From header alongside the mailbox address.", "type": "string", "example": "John Doe" }, "cc": { "description": "Carbon-copy recipient email addresses.", "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "cc@example.com" ] }, "bcc": { "description": "Blind-carbon-copy recipient email addresses. Not visible to other recipients.", "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "bcc@example.com" ] }, "subject": { "description": "Message subject line.", "type": "string", "example": "Hello" }, "text": { "description": "Plain-text body. Optional; if both text and html are omitted the message is sent without a body.", "type": "string", "example": "Plain body" }, "html": { "description": "HTML body. Optional; if both text and html are omitted the message is sent without a body. Inline images are referenced via cid: URLs matching attachment cid values.", "type": "string", "example": "

HTML body

" }, "attachments": { "description": "Files to attach. Inline images set cid; regular attachments omit it.", "type": "array", "items": { "$ref": "#/components/schemas/V1.Send.Attachment" } }, "inReplyTo": { "description": "Source message this is a reply to. Copies its Message-Id/References into In-Reply-To/References and flags it \\Answered. Mutually exclusive with forwardOf.", "allOf": [ { "$ref": "#/components/schemas/V1.Send.MessageRef" } ] }, "forwardOf": { "description": "Source message this forwards. Copies its Message-Id/References into In-Reply-To/References and flags it $forwarded. Mutually exclusive with inReplyTo.", "allOf": [ { "$ref": "#/components/schemas/V1.Send.MessageRef" } ] } }, "type": "object", "anyOf": [ { "required": [ "to" ] }, { "required": [ "cc" ] }, { "required": [ "bcc" ] } ] }, "V1.Webhooks.Collection": { "description": "Paginated list of webhooks.", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1.Webhooks.Webhook" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" }, "V1.Webhooks.CreateRequest": { "description": "Body for creating a webhook.", "required": [ "name", "events", "url" ], "properties": { "name": { "description": "Human-readable webhook name.", "type": "string", "example": "New message notifier", "maxLength": 255 }, "description": { "description": "Optional free-text note about the webhook purpose.", "type": "string", "example": "Notifies CRM on new mail", "nullable": true }, "events": { "description": "Event types that trigger a delivery.", "type": "array", "items": { "type": "string", "enum": [ "message.received" ] }, "example": [ "message.received" ] }, "status": { "description": "Initial delivery state. Only active webhooks receive events.", "type": "string", "example": "active", "default": "active", "enum": [ "active", "paused", "disabled" ] }, "url": { "description": "HTTPS endpoint that receives POST deliveries, authenticated with the webhook secret as `Authorization: Bearer `. Must be a public domain name (no IPs or internal hosts).", "type": "string", "format": "uri", "example": "https://example.com/webhooks/incoming", "maxLength": 2048 } }, "type": "object" }, "V1.Webhooks.Resource": { "description": "Single webhook payload.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/V1.Webhooks.Webhook" } }, "type": "object" }, "V1.Webhooks.ResourceWithSecret": { "description": "Single webhook payload including the one-time secret.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/V1.Webhooks.WebhookWithSecret" } }, "type": "object" }, "V1.Webhooks.TestResult": { "description": "Result of a webhook test delivery.", "required": [ "data" ], "properties": { "data": { "required": [ "httpStatus" ], "properties": { "httpStatus": { "type": "integer", "example": 200 }, "success": { "type": "boolean", "example": true }, "error": { "type": "string", "example": "Connection refused", "nullable": true } }, "type": "object" } }, "type": "object" }, "V1.Webhooks.UpdateRequest": { "description": "Body for partially updating a webhook. All fields optional; only present fields are applied.", "properties": { "name": { "description": "Human-readable webhook name.", "type": "string", "example": "Renamed webhook", "maxLength": 255 }, "description": { "description": "Free-text note about the webhook purpose. Send null to clear.", "type": "string", "example": "Updated description", "nullable": true }, "events": { "description": "Event types that trigger a delivery. Replaces the current list.", "type": "array", "items": { "type": "string", "enum": [ "message.received" ] }, "example": [ "message.received" ], "minItems": 1 }, "status": { "description": "Delivery state. Only active webhooks receive events; paused keeps config but stops deliveries.", "type": "string", "example": "paused", "enum": [ "active", "paused", "disabled" ] }, "url": { "description": "HTTPS endpoint that receives POST deliveries, authenticated with the webhook secret as `Authorization: Bearer `. Must be a public domain name (no IPs or internal hosts).", "type": "string", "format": "uri", "example": "https://example.com/webhooks/new", "maxLength": 2048 } }, "type": "object" }, "V1.Webhooks.Webhook": { "description": "Webhook configured for a managed mailbox.", "required": [ "id", "accountResourceId", "mailbox", "name", "description", "events", "status", "url", "createdAt", "updatedAt" ], "properties": { "id": { "description": "Unique webhook identifier (UUID v7).", "type": "string", "format": "uuid", "example": "019683f8-1234-7abc-8def-0123456789ab" }, "accountResourceId": { "description": "Resource ID of the mailbox this webhook is attached to.", "type": "string", "pattern": "^AC[A-Za-z0-9]+$", "example": "AC1a2b3c4d5e6f7g" }, "mailbox": { "description": "Email address of the mailbox.", "type": "string", "example": "user@example.com" }, "name": { "type": "string", "example": "New message notifier", "maxLength": 255 }, "description": { "type": "string", "example": "Notifies our CRM when a new email arrives", "nullable": true }, "events": { "type": "array", "items": { "type": "string", "example": "message.received", "enum": [ "message.received" ] } }, "status": { "type": "string", "example": "active", "enum": [ "active", "paused", "disabled" ] }, "url": { "type": "string", "format": "uri", "example": "https://example.com/webhooks/incoming", "maxLength": 2048 }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-04-07T12:00:00+00:00" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-04-07T12:00:00+00:00" } }, "type": "object" }, "V1.Webhooks.WebhookWithSecret": { "description": "Webhook payload that includes the one-time `secret`. Returned at creation and after secret regeneration. The secret is delivered as a bearer token on every webhook request (`Authorization: Bearer `); store it securely as it is not returned again.", "required": [ "secret" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/V1.Webhooks.Webhook" }, { "properties": { "secret": { "type": "string", "example": "4a6f8b2d1e9c3f7a0b5d8e2c4f1a7b3d9e6c2f8a1b4d7e0c3f6a9b2d5e8c1f4" } }, "type": "object" } ] } }, "responses": { "Common.Response.BadGatewayResponse": { "description": "Upstream service is unavailable or returned an unexpected response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Upstream service unavailable.", "code": "ERR_UPSTREAM_UNAVAILABLE", "params": [] } } } }, "Common.Response.ConflictResponse": { "description": "Conflict with the target resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Resource conflict.", "code": "ERR_CONFLICT", "params": [] } } } }, "Common.Response.ForbiddenResponse": { "description": "Token is not authorized to manage the requested mailbox.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Forbidden.", "code": "ERR_FORBIDDEN", "params": [] } } } }, "Common.Response.GatewayTimeoutResponse": { "description": "Upstream service did not respond within the configured timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Upstream service timed out.", "code": "ERR_GATEWAY_TIMEOUT", "params": [] } } } }, "Common.Response.InternalServerErrorResponse": { "description": "Server-side failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Internal server error.", "code": "ERR_INTERNAL_SERVER_ERROR", "params": [] } } } }, "Common.Response.NotFoundResponse": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Resource not found.", "code": "ERR_NOT_FOUND", "params": [] } } } }, "Common.Response.TooManyRequestsResponse": { "description": "Feedback for this customer was submitted less than ten seconds ago. Wait and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Feedback was submitted too recently. Try again later.", "code": "ERR_FEEDBACK_RATE_LIMIT", "params": [] } } } }, "Common.Response.UnauthorizedResponse": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Missing or invalid credentials.", "code": "ERR_UNAUTHORIZED", "params": [] } } } }, "Common.Response.ValidationFailedResponse": { "description": "Request payload failed validation. `params` maps field name to an array of error messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "The given data was invalid.", "code": "ERR_VALIDATION_FAILED", "params": { "name": [ "name is required" ] } } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "description": "Bearer authentication using API tokens in the Authorization header.", "scheme": "bearer" } } }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Account", "description": "Inspect the authenticated account and the mailboxes it can manage." }, { "name": "Folders", "description": "Manage IMAP folders inside a managed mailbox." }, { "name": "Messages", "description": "Read, search, and manage messages inside a managed mailbox." }, { "name": "Send", "description": "Send mail through the managed mailbox." }, { "name": "Webhooks", "description": "Manage webhooks for a managed mailbox." }, { "name": "Quota", "description": "Inspect storage and message quota usage for a managed mailbox." }, { "name": "Feedback", "description": "Report problems or suggestions about this API or the MCP server. Report after a call failed or returned unexpected data, when documentation was missing or unclear, when a response was too slow, or when a capability you need does not exist. Mention the failing operation and status code in the message; never include tokens or email contents." } ], "x-mcp-instructions": "Hostinger Mail API access — use this server when the user wants to read, search, send, organize, or manage email in their Hostinger mailbox(es), or manage email webhooks.\n\nCapabilities:\n- List mailboxes belonging to the authenticated Hostinger order\n- List folders inside a mailbox (Inbox, Sent, Drafts, Trash, custom)\n- List, search, fetch, move, delete, flag messages\n- Read message body (text/HTML), full RFC822 source, attachments\n- Send email from a mailbox\n- Manage webhooks (create, list, test, regenerate secret, delete)\n- Send the user's feedback about this API to the Hostinger mail team (`POST /api/v1/mailboxes/{mailboxResourceId}/feedback`)\n\nMailbox discovery: there is no standalone \"list mailboxes\" endpoint. Call `GET /api/v1/me` first — the response contains `data.mailboxes[]` with each mailbox's `resourceId` and `address`. Use that `resourceId` as `mailboxResourceId` in every other endpoint.\n\nEvery operation is exposed as its own tool; use only the tools that are listed. Path templates use `{placeholder}` substitution.\n\nAuth: each request must carry `Authorization: Bearer `. Tokens are scoped to one Hostinger order and may be further restricted to specific mailboxes within that order — assume access is partial unless verified.\n\nFeedback: only call `POST /api/v1/mailboxes/{mailboxResourceId}/feedback` when the user explicitly asks to send feedback, report a problem, or request a feature. Send the user's own words, keep it under 2000 characters, and never include tokens, passwords or email contents." }