{ "openapi": "3.1.0", "info": { "title": "MailAPI", "version": "1.0.0", "description": "Background jobs return a `task_id`. Poll the matching get-task endpoint until `completed` or `failed`. Bulk domain deletes: up to 10 hostnames per request. Bulk mailbox deletes: up to 100 addresses per request. One bulk-delete request per 5 minutes per API key and IP. HTTP 422 validation errors do not count toward the cooldown. Active pricing plan required (admins exempt)." }, "servers": [ { "url": "https://mailapi.tech/api" } ], "paths": { "/v1/create/domain": { "post": { "summary": "Create Domain", "description": "Creates a new base domain in your MailAPI workspace and queues provisioning in the background.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nInvalid hostnames return HTTP 422 before enqueue; duplicates return HTTP 409.\n\nPoll `GET /api/v1/get/domain?task_id=…`. When `completed`, `results` includes DNS `records` (MX/TXT/A).\n\nRemote mail server defaults apply on provision; quota fields are not accepted on this request.", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "domain": "example.com", "task_id": 101 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "This domain is already registered on MailAPI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "First validation error message (invalid body fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Domain": { "type": "string", "description": "Fully qualified hostname (e.g. example.com). Omit http(s)://; single-label names are rejected (same rules as the dashboard Add domain form)." }, "Params": { "type": "object", "description": "Optional keys (for example `total_mailbox_allowed`)." } }, "required": [ "Domain" ] } } } } } }, "/v1/get/domain": { "get": { "summary": "Get Domain Task", "description": "Polls a root domain create task created by `POST /api/v1/create/domain`.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`status` may be `queued`, `running`, `completed`, or `failed`. Only `failed` returns HTTP 422 with `reason` from the task.\n\nWhile `queued` or `running`, `results` is often an empty array until the job finishes.\n\nResponses include `Task_id` (integer) and `task_id` (same value as a string).", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "Task_id": 101, "total_email": 0, "domain": "example.com", "results": { "domain": "example.com", "status": "Created successfully.", "records": [ { "type": "MX", "name": "example.com", "value": "mx1.mailapi.tech", "priority": "10", "status": "Not checked" }, { "type": "MX", "name": "example.com", "value": "mx2.mailapi.tech", "priority": "20", "status": "Not checked" }, { "type": "TXT", "name": "_mailapi.example.com", "value": "", "priority": "—", "status": "Not checked" } ] }, "status": "completed", "task_id": "101" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from the queue job (same shape as other errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by Create Domain." } ] } }, "/v1/create/sub-domain": { "post": { "summary": "Create Sub-Domain Batch", "description": "Creates up to 10 sub-domains under an existing parent domain in a single queued task.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nAfter a successful run: at most one request per 5 minutes per API key and parent domain.\n\nPoll `GET /api/v1/get/sub-domain?task_id=…`. When `completed`, nested `results` are keyed by FQDN.\n\nProvisioning uses the same remote defaults as Create Domain; quota fields are not accepted.", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "domain": "example.com", "task_id": 202 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Parent domain was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Params.sub_domains must be a non-empty array (or validation on labels). Maximum 10 sub-domains are allowed per request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Sub-domain requests are limited to once per 5 minutes for this domain and API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Domain": { "type": "string", "description": "Existing parent (root) domain owned by your account. Must be a valid dotted hostname (same rules as Create Domain / dashboard)." } }, "required": [ "Domain" ] } } } } } }, "/v1/get/sub-domain": { "get": { "summary": "Get Sub-Domain Task", "description": "Polls a sub-domain batch task from `POST /api/v1/create/sub-domain`.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`status` values are the same as other task endpoints (`queued`, `running`, `completed`, `failed`).\n\nResponses include `Task_id` (integer) and `task_id` (same value as a string).", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "Task_id": 202, "total_email": 0, "domain": "example.com", "results": { "domain": "example.com", "results": { "team.example.com": { "status": "Created successfully.", "records": [ { "type": "MX", "name": "team.example.com", "value": "mx1.mailapi.tech", "priority": "10", "status": "Not checked" }, { "type": "MX", "name": "team.example.com", "value": "mx2.mailapi.tech", "priority": "20", "status": "Not checked" } ] }, "support.example.com": { "status": "Created successfully.", "records": [ { "type": "MX", "name": "support.example.com", "value": "mx1.mailapi.tech", "priority": "10", "status": "Not checked" }, { "type": "MX", "name": "support.example.com", "value": "mx2.mailapi.tech", "priority": "20", "status": "Not checked" } ] } } }, "status": "completed", "task_id": "202" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from provisioning.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by Create Sub-Domain." } ] } }, "/v1/list/domain": { "get": { "summary": "List Domains", "description": "Returns all domains for the API key owner account, keyed by domain name.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`domain_type` is `root` or `sub`.\n\n`domain_quota` is a string with a `GB` suffix; `0GB` means unlimited in list responses (non-zero may appear on older rows).", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "total_domain": 2, "results": { "example.com": { "status": "verified", "domain_type": "root", "domain_quota": "0GB", "mailbox_count": "15", "created_at": "14-04-2026" }, "team.example.com": { "status": "verified", "domain_type": "sub", "domain_quota": "0GB", "mailbox_count": "3", "created_at": "15-04-2026" } }, "status": "success" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ] } }, "/v1/create/mailbox/single": { "post": { "summary": "Create Single Mailbox", "description": "Queues one mailbox creation request for a domain that belongs to your account.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nInvalid bodies return HTTP 422 before enqueue. Only numeric `0` for `Params.password` triggers auto-generation (string `\"0\"` is rejected).\n\nPoll `GET /api/v1/get/mailbox/single?task_id=…`; remote failures return HTTP 422 on that poll.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 123 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Domain not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "First validation error message (invalid body fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Email_fullname": { "type": "string", "description": "Display name stored on the mailbox (not the email local-part)." }, "single_bulk": { "type": "string", "description": "Must be `single`." }, "Domain": { "type": "string", "description": "Target domain hostname." }, "Params": { "type": "object", "description": "Payload object for mailbox provisioning details." } }, "required": [ "Email_fullname", "single_bulk", "Domain", "Params" ] } } } } } }, "/v1/create/mailbox/bulk": { "post": { "summary": "Create Bulk Mailboxes", "description": "Queues a bulk mailbox provisioning task and returns a task ID for later retrieval.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nAfter a successful run: at most one bulk create per 5 minutes per API key and target hostname.\n\n`Params.mailbox_no` must be between 1 and 100.\n\nIf a generated mailbox address already exists, it is skipped and the task continues creating the remaining addresses.\n\nIf all requested addresses already exist, the task still completes successfully with `total_email` set to `0` and an empty `results` object.\n\nOnly numeric `0` for `Params.password` triggers per-mailbox auto-generation (string `\"0\"` is rejected).\n\nPoll `GET /api/v1/get/mailbox/bulk?task_id=…`; remote failures return HTTP 422 on that poll.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 456 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Domain not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "First validation error message (invalid body fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Bulk mailbox requests are limited to once per 5 minutes for this domain and API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Email_fullname": { "type": "string", "description": "Display name used with internal rules to derive unique mailbox local-parts." }, "single_bulk": { "type": "string", "description": "Must be `bulk`." }, "Domain": { "type": "string", "description": "Target domain hostname." }, "Params": { "type": "object", "description": "Payload object for mailbox provisioning details." } }, "required": [ "Email_fullname", "single_bulk", "Domain", "Params" ] } } } } } }, "/v1/get/mailbox/single": { "get": { "summary": "Get Single Mailbox Task", "description": "Fetches status and final result for a single mailbox provisioning task.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`status` is `queued`, `running`, `completed`, or `failed`. While pending, `results` is often empty.\n\nBoth `Task_id` (int) and `task_id` (string) are returned with the same value.\n\nWhen `completed`, each entry includes `email`, `password`, `quota`, `domain`, `provisioning`, `create_date` (no per-entry `status`).\n\nIf create used `Params.password: 0`, the response `password` is generated per mailbox.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "Task_id": 123, "total_email": 1, "domain": "example.com", "results": { "john@example.com": { "email": "john@example.com", "password": "SecurePass123", "quota": "0MB", "domain": "example.com", "provisioning": "pending", "create_date": "2026-04-26 16:45:00" } }, "status": "completed", "task_id": "123" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from `error_message` when the task fails.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by create endpoint." } ] } }, "/v1/get/mailbox/bulk": { "get": { "summary": "Get Bulk Mailbox Task", "description": "Fetches status and per-mailbox results for a bulk mailbox provisioning task.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`status` follows the same lifecycle as single mailbox tasks.\n\nResponses include `Task_id` (integer) and `task_id` (same value as a string).\n\nWhen some requested addresses already exist, those addresses are skipped and `total_email` reflects only newly created mailboxes.\n\nIf all requested addresses already exist, the task still completes successfully with `total_email` set to `0` and an empty `results` object.\n\nResults include mailbox-by-mailbox status details when `completed`.\n\nIf bulk create used numeric `Params.password: 0`, each mailbox result includes its own generated `password` value.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "Task_id": 456, "total_email": 25, "domain": "example.com", "results": { "team1@example.com": { "status": "Created successfully.", "password": "kL4!pQ9#uD2@xM7&zT8w" }, "team2@example.com": { "status": "Created successfully.", "password": "rN6$hS1*eV0!cB3%yK5m" } }, "status": "completed", "task_id": "456" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from `error_message` when the task fails.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by bulk create endpoint." } ] } }, "/v1/delete/domain/bulk": { "post": { "summary": "Bulk Delete Domains", "description": "Queues removal of up to 10 domains (root or sub-domain hostnames) owned by your account. Deletes run sequentially on the mail server; there is no artificial delay between items.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key` with `write` permission.\n\nCooldown: one successfully enqueued call per 5 minutes per API key and IP; HTTP 422 does not count. Mailbox bulk delete uses a separate counter of the same length.\n\nPoll `GET /api/v1/get/delete/domain/bulk?task_id=…` until `completed` or `failed`.\n\nWhen `completed`, `results` entries use `deleted`, `failed`, or `skipped` with optional `reason`; partial failures still yield task `completed`.\n\nDeleting a root domain removes descendant hostnames and their mailboxes in dependency order.", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 801 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create, bulk-delete, or manage domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error (empty array, too many domains, invalid hostname, or duplicate entries).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests (bulk domain delete is limited to one successfully enqueued call per 5 minutes per API key and IP).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Domains": { "type": "array", "items": { "type": "string" }, "description": "Fully qualified hostnames to remove (1–10 per request). Duplicates are rejected. Same hostname rules as create domain (no scheme; valid dotted hostname)." } }, "required": [ "Domains" ] } } } } } }, "/v1/get/delete/domain/bulk": { "get": { "summary": "Get Bulk Delete Domains Task", "description": "Polls a bulk domain delete task created by `POST /api/v1/delete/domain/bulk`.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key` with `read` permission.\n\n`status` may be `queued`, `running`, `completed`, or `failed`. Only `failed` (task-level) returns HTTP 422 with `reason` from the task.\n\nPer-domain outcomes (`deleted`, `failed`, or `skipped`) appear inside `results` while the overall task can still be `completed`.", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "Task_id": 801, "total_email": 0, "domain": "old.example.com", "results": { "old.example.com": { "status": "deleted" }, "legacy.example.com": { "status": "failed", "reason": "Mail server rejected domain removal." }, "missing.example.com": { "status": "skipped", "reason": "Domain not found for this account." } }, "status": "completed", "task_id": "801" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from `error_message` when the task fails.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by Bulk Delete Domains." } ] } }, "/v1/delete/mailbox/bulk": { "post": { "summary": "Bulk Delete Mailboxes", "description": "Queues removal of up to 100 mailbox addresses owned by your account. Deletes run sequentially; there is no artificial delay between items.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key` with `write` permission.\n\nCooldown: one successfully enqueued call per 5 minutes per API key and IP; HTTP 422 does not count. Domain bulk delete uses a separate counter of the same length.\n\nPoll `GET /api/v1/get/delete/mailbox/bulk?task_id=…` until `completed` or `failed`.\n\nWhen `completed`, `results` entries use `deleted`, `failed`, or `skipped` with optional `reason`.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 802 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create, bulk-delete, or manage domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error (empty array, too many addresses, invalid email, or duplicate entries).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests (bulk mailbox delete is limited to one successfully enqueued call per 5 minutes per API key and IP).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Mailboxes": { "type": "array", "items": { "type": "string" }, "description": "Full RFC email addresses (1–100 per request). Duplicates are rejected." } }, "required": [ "Mailboxes" ] } } } } } }, "/v1/get/delete/mailbox/bulk": { "get": { "summary": "Get Bulk Delete Mailboxes Task", "description": "Polls a bulk mailbox delete task created by `POST /api/v1/delete/mailbox/bulk`.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key` with `read` permission.\n\n`total_email` mirrors the request size (count of addresses submitted), not the number successfully deleted.\n\nPer-mailbox outcomes (`deleted`, `failed`, or `skipped`) appear inside `results` while the overall task can still be `completed`.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "Task_id": 802, "total_email": 2, "domain": "example.com", "results": { "a@example.com": { "status": "deleted" }, "b@example.com": { "status": "failed", "reason": "Mail server rejected mailbox removal." }, "gone@example.com": { "status": "skipped", "reason": "Mailbox not found for this account." } }, "status": "completed", "task_id": "802" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from `error_message` when the task fails.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by Bulk Delete Mailboxes." } ] } }, "/v1/list/mailbox": { "get": { "summary": "List Mailboxes", "description": "Returns all mailboxes for a specific owned domain, keyed by full email address.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`imap_credentials` only when `include_credentials=true`.\n\n`mailbox_quota` is a string with an `MB` suffix; `0MB` means unlimited (non-zero may appear on older rows).", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "domain": "example.com", "results": { "john@example.com": { "provisioning_status": "active", "mailbox_quota": "0MB", "imap_credentials": { "host": "imap.example.com", "port": 993, "encryption": "tls" }, "created_at": "14-04-2026" } }, "status": "success" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Domain not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Domain to list mailboxes for." }, { "name": "include_credentials", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include `imap_credentials` in each mailbox result when true." } ] } }, "/v1/mail/inbound": { "post": { "summary": "Inbound Email", "description": "Accepts inbound payloads for a tenant mailbox and queues processing. Optional fields include `from_name`, `cc`, `bcc`, `body_html`, `attachments`, and `headers`.\n\nRequires API key with `inbound` permission.\n\nInbound processing is asynchronous.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "accepted", "message_id": "" } } } }, "401": { "description": "API key is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks inbound permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Duplicate message_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unknown mailbox or invalid payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string", "description": "Upstream message identifier. Must be unique per mailbox." }, "from_email": { "type": "string", "description": "Sender email address." }, "to_email": { "type": "string", "description": "Recipient mailbox address owned by your tenant." }, "subject": { "type": "string", "description": "Email subject line." }, "received_at": { "type": "string", "description": "Inbound receive timestamp." } }, "required": [ "message_id", "from_email", "to_email", "subject", "received_at" ] } } } } } }, "/v1/emails": { "get": { "summary": "List Emails", "description": "Returns tenant-scoped inbox emails with cursor pagination.\n\nRequires API key with `read` permission.\n\nQuery is always tenant-isolated.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [], "meta": { "next_cursor": null, "prev_cursor": null } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks read permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "mailbox_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter by mailbox." }, { "name": "unread", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Return unread only." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter received_at lower bound." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter received_at upper bound." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search subject, body text, or sender address." } ] } }, "/v1/emails/{email}": { "get": { "summary": "Get Email", "description": "Returns one tenant-scoped email with attachment metadata.\n\nRequires API key with `read` permission.\n\nSoft-deleted records are not returned from this endpoint.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 123 } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Email not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Email record ID (route parameter `{email}`)." } ] }, "delete": { "summary": "Delete Email", "description": "Soft-deletes an email and emits an email.deleted webhook event.\n\nRequires API key with `write` permission.\n\nRecord is soft deleted, not permanently removed.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks write permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Email not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Email record ID (route parameter `{email}`)." } ] } }, "/v1/emails/sync": { "get": { "summary": "Sync Emails", "description": "Incremental polling endpoint for new, updated, and deleted emails.\n\nRequires API key with `read` permission.\n\nDeleted emails are returned with deletion markers to support tombstones.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [], "meta": { "next_cursor": null, "prev_cursor": null } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The since field is required and must be a valid date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "since", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Sync lower bound using updated markers." } ] } }, "/v1/emails/{email}/read": { "post": { "summary": "Mark Email Read", "description": "Marks an email as read and emits an email.read webhook event.\n\nRequires API key with `write` permission.\n\nThis endpoint is idempotent.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks write permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Email not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Email record ID (route parameter `{email}`)." } ] } }, "/v1/emails/{email}/attachments/{attachment}": { "get": { "summary": "Attachment URL", "description": "Returns a temporary signed attachment download URL.\n\nRequires API key with `read` permission.\n\nURL expires shortly after issuance.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "url": "https://signed-url", "expires_at": "2026-04-28T10:10:00Z" } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Email or attachment not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Email record ID (route parameter `{email}`)." }, { "name": "attachment", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Attachment record ID (route parameter `{attachment}`)." } ] } }, "/v1/webhooks": { "post": { "summary": "Register Webhook", "description": "Creates a tenant-scoped webhook target for email events.\n\nRequires API key with `webhook` permission.\n\nDeliveries are queued and signed using the webhook secret and timestamp headers.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 1 } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks webhook permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid URL or event selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Destination webhook URL." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Allowed values: email.received, email.read, email.deleted." } }, "required": [ "url", "events" ] } } } } }, "get": { "summary": "List Webhooks", "description": "Returns tenant-scoped webhook endpoints.\n\nRequires API key with `webhook` permission.\n\nEach row includes `last_triggered_at` when the webhook has fired.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 1, "url": "https://example.com/hook", "events": [ "email.received" ], "is_active": true } ] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks webhook permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ] } }, "/v1/webhooks/{webhook}": { "patch": { "summary": "Update Webhook", "description": "Updates URL, events, or active state.\n\nRequires API key with `webhook` permission.\n\nInclude at least one of `url`, `events`, or `is_active`.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks webhook permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid URL or event selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook ID (route parameter `{webhook}`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Destination webhook URL." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Allowed values: email.received, email.read, email.deleted." }, "is_active": { "type": "boolean", "description": "Whether webhook should receive deliveries." } } } } } } }, "delete": { "summary": "Delete Webhook", "description": "Deletes a tenant webhook endpoint.\n\nRequires API key with `webhook` permission.\n\nPermanent delete; queued delivery rows for this webhook are removed.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks webhook permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook ID (route parameter `{webhook}`)." } ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Send API keys via `Authorization: Bearer ` or `X-Api-Key` headers only." }, "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "32 characters (alpha-numeric)" } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "status", "reason" ], "properties": { "status": { "type": "string", "enum": [ "error" ] }, "reason": { "type": "string" } } }, "TaskResponse": { "type": "object", "required": [ "status", "task_id" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "task_id": { "type": "integer" }, "domain": { "type": "string" } } } } } }