diff --git a/static/openapi.yaml b/static/openapi.yaml index 4c4147b..9b02a8f 100644 --- a/static/openapi.yaml +++ b/static/openapi.yaml @@ -1,39 +1,33 @@ openapi: 3.0.0 info: description: >- - docker-mailserver, or DMS for short, is a production-ready fullstack but simple mail server - (SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.). It employs only configuration files, no SQL database. - The image is focused around the slogan "Keep it simple and versioned". + docker-mailserver is a production-ready fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.) running inside a container. - docker-mailserver-webapi is a REST API that helps you efficiently - manage your docker-mailserver configuration. - It uses docker-mailserver setup.sh as a bridge for managing configurations. - - - In order to use this API you need a API key and add your IP - address to the whitelist of allowed IPs this can be done by add new environment variable - WEB_API_KEY and WEB_API_WHITELISTED_IP in your compose file. + docker-mailserver-webapi is a REST API that helps you efficiently manage your docker-mailserver configuration. It uses the docker-mailserver `setup.sh` as a bridge for managing configurations. + + In order to use this API, you need to add an API key and your IP address to a whitelist of allowed IPs. + Create a [*`webapi.env`*](https://github.com/bramanda48/docker-mailserver-webapi/blob/master/.env.example) file with the variables from this [example file](https://github.com/bramanda48/docker-mailserver-webapi/blob/master/.env.example) and bind it to the Docker container under `/tmp/docker-mailserver/webapi/.env`. title: Docker Mailserver - Web API version: "1.0.0" servers: - url: "{protocol}://{host}:{port}/{baseUrl}" - description: '' + description: "" variables: protocol: default: http enum: - http - https - description: The protocol used to access the server. + description: The protocol used to make requests to the API. host: default: localhost description: The hostname or IP address of the server. port: default: "3000" - description: The port number on which the server is listening for requests + description: The port number on which the API is listening for requests. baseUrl: default: "" description: The base URL path for all API endpoints. This can be used to group related endpoints together under a common path. @@ -47,34 +41,31 @@ components: security: - ApiKeyAuth: [] - + tags: - - name: DKIM (DomainKeys Identified Mail) - description: Manage DKIM Keys - - name: Mail Account - description: You can manage mail account. + - name: DKIM + description: Manage DKIM (DomainKeys Identified Mail) Keys + - name: Accounts + description: Manage mail accounts. - name: Aliases - description: You can manage aliases. + description: Manage mail account aliases. - name: Quota - description: You can manage quota. + description: Manage mail account quotas. - name: Dovecot - description: You can manage dovecot master and etc. - - name: Relay - description: You can manage relay-host service. - - name: Fail2ban - description: Manage netfilter fail2ban. + description: Manage the Dovecot master account. + - name: Relays + description: Manage relay-host services. + - name: Fail2Ban + description: Manage Fail2Ban IP bans. - name: Logs - description: Manage docker mailserver logs. - + description: Get logs from various services. + paths: - ############################################################################ - # DKIM Manager - ############################################################################ /api/v1/config/dkim: post: tags: - - DKIM (DomainKeys Identified Mail) - summary: Creates DKIM keys and configures them within DMS. + - DKIM + summary: Creates DKIM keys and configures them within docker-mailserver. operationId: setup-dkim requestBody: description: | @@ -101,7 +92,7 @@ paths: selector: type: string example: "mail" - domain: + domain: type: string example: "example.com" keytype: @@ -119,25 +110,88 @@ paths: responses: 200: description: Success - - - ############################################################################ - # Mail Account - ############################################################################ + /api/v1/email: - get: + get: tags: - - Mail Account - summary: Get all registered mail account. + - Accounts + summary: Get all registered mail accounts. operationId: get-email responses: 200: - description: Success - - post: + description: Response contains all registered mail accounts. + content: + application/json: + schema: + type: object + properties: + statusCode: + type: integer + example: 200 + metadata: + type: object + properties: + request: + type: object + properties: + timestamp: + type: string + format: date-time + example: "2024-09-19T14:56:37.706Z" + method: + type: string + example: "GET" + path: + type: string + example: "/api/v1/email" + pagination: + type: object + nullable: true + data: + type: array + items: + type: object + properties: + email: + type: string + example: "user@example.com" + password: + type: string + description: Password in SHA512 + alias: + type: array + items: + type: object + properties: + emailAlias: + type: string + example: "alias@example.com" + quota: + type: object + properties: + quotaUsed: + type: integer + example: 0 + quotaUsedPercent: + type: integer + example: 0 + quota: + type: integer + example: 0 + restriction: + type: object + properties: + send: + type: boolean + example: false + receive: + type: boolean + example: false + + post: tags: - - Mail Account - summary: Add a new mail account (email address). + - Accounts + summary: Create a new mail account. operationId: add-email requestBody: required: true @@ -155,11 +209,11 @@ paths: responses: 200: description: Success - - patch: + + patch: tags: - - Mail Account - summary: Update the password for a mail account. + - Accounts + summary: Update the password of a mail account. operationId: update-email requestBody: required: true @@ -177,14 +231,13 @@ paths: responses: 200: description: Success - - delete: + + delete: tags: - - Mail Account - summary: Delete a mail account, including associated data (aliases, quotas) and - optionally the mailbox storage for that account. + - Accounts + summary: Delete a mail account including associated data (aliases, quotas) and optionally the mailbox storage for that account. operationId: delete-email - parameters: + parameters: - in: query name: email schema: @@ -195,15 +248,14 @@ paths: responses: 200: description: Success - - + /api/v1/email/restrict: - get: + get: tags: - - Mail Account + - Accounts summary: Display restricted mail accounts. operationId: get-email-restrict - parameters: + parameters: - in: query name: email schema: @@ -214,11 +266,11 @@ paths: responses: 200: description: Success - - post: + + post: tags: - - Mail Account - summary: Add a mail account to restricted list. + - Accounts + summary: Add a mail account to the restricted list. operationId: add-email-restrict requestBody: description: | @@ -244,13 +296,13 @@ paths: responses: 200: description: Success - - delete: + + delete: tags: - - Mail Account + - Accounts summary: Remove a mail account from the restricted list. operationId: delete-email-restrict - parameters: + parameters: - in: query name: access schema: @@ -270,13 +322,9 @@ paths: responses: 200: description: Success - - - ############################################################################ - # Alias - ############################################################################ + /api/v1/alias: - post: + post: tags: - Aliases summary: Add an alias for a recipient (a mail account). @@ -299,14 +347,14 @@ paths: responses: 200: description: Success - - delete: + + delete: tags: - Aliases - summary: Remove a mail account (the recipient) from an existing alias. + summary: Remove a mail account (the recipient) from an existing alias. operationId: delete-alias description: "If the alias has no more recipients, the alias will also be removed." - parameters: + parameters: - in: query name: emailAlias schema: @@ -324,16 +372,12 @@ paths: responses: 200: description: Success - - - ############################################################################ - # Quota - ############################################################################ + /api/v1/quota: - patch: + patch: tags: - Quota - summary: Set a quota (storage limit) for an existing mail account. + summary: Set a quota (storage limit) for an existing mail account. operationId: update-quota requestBody: description: | @@ -357,13 +401,13 @@ paths: responses: 200: description: Success - - delete: + + delete: tags: - Quota summary: Remove any quota set for an existing mail account. operationId: delete-quota - parameters: + parameters: - in: query name: email schema: @@ -374,25 +418,21 @@ paths: responses: 200: description: Success - - - ############################################################################ - # Dovecot - ############################################################################ + /api/v1/dovecot/master: - get: + get: tags: - Dovecot - summary: Get list dovecot-master account. + summary: Get a list of all Dovecot master accounts. operationId: get-dovecot-master responses: 200: description: Success - - post: + + post: tags: - Dovecot - summary: Add a new dovecot-master account (for POP3/IMAP administration). + summary: Add a new Dovecot master account (for POP3/IMAP administration). operationId: add-dovecot-master requestBody: required: true @@ -410,11 +450,11 @@ paths: responses: 200: description: Success - - patch: + + patch: tags: - Dovecot - summary: Update the password for a dovecot-master account. + summary: Update the password for a Dovecot master account. operationId: update-dovecot-master requestBody: required: true @@ -432,13 +472,13 @@ paths: responses: 200: description: Success - - delete: + + delete: tags: - Dovecot - summary: Remove a dovecot-master account. + summary: Delete a Dovecot master account. operationId: delete-dovecot-master - parameters: + parameters: - in: query name: username schema: @@ -451,17 +491,12 @@ paths: responses: 200: description: Success - - - - ############################################################################ - # Relay - ############################################################################ + /api/v1/relay/add-auth: - post: + post: tags: - - Relay - summary: Add credentials to authenticate to a relay-host service. + - Relays + summary: Add credentials to authenticate to a relay-host service. operationId: relay-add-auth requestBody: required: true @@ -482,20 +517,19 @@ paths: responses: 200: description: Success - - + /api/v1/relay/add-domain: - post: + post: tags: - - Relay - summary: Add domain to relay-host service. + - Relays + summary: Add a domain to a relay-host service. operationId: relay-add-domain description: | Add a relay-host where mail sent from mail accounts of the provided, domain will be relayed through to their destination. - + If a port is not provided it will default to 25. - + If the relay-host requires authentication, use the 'setup relay add-auth' command after adding the relay-host. requestBody: @@ -517,18 +551,17 @@ paths: responses: 200: description: Success - - + /api/v1/relay/exclude-domain: - post: + post: tags: - - Relay - summary: Exclude the domain from relay-host service. + - Relays + summary: Exclude a domain from a relay-host service. operationId: relay-exclude-domain description: | When a default relay-host is configured (via ENV), the default behaviour is to relay all your mail accounts outgoing mail through that service. - + This command allows to opt-out from that default behaviour by excluding all mail accounts belonging to a hosted domain you specify. requestBody: @@ -544,28 +577,24 @@ paths: responses: 200: description: Success - - - ############################################################################ - # Fail2ban - ############################################################################ + /api/v1/fail2ban: - get: + get: tags: - - Fail2ban - summary: Get all banned IP Address. + - Fail2Ban + summary: Get all banned IP addresses. operationId: get-fail2ban responses: 200: description: Success - + /api/v1/fail2ban/ban/{ip}: - post: + post: tags: - - Fail2ban - summary: Add IP Address to the custom jail. + - Fail2Ban + summary: Add an IP address to the custom jail. operationId: ban-fail2ban - parameters: + parameters: - in: path name: ip schema: @@ -576,14 +605,14 @@ paths: responses: 200: description: Success - + /api/v1/fail2ban/unban/{ip}: - post: + post: tags: - - Fail2ban - summary: Unban IP Address. + - Fail2Ban + summary: Unban and IP address. operationId: unban-fail2ban - parameters: + parameters: - in: path name: ip schema: @@ -595,17 +624,13 @@ paths: 200: description: Success - - ############################################################################ - # Logs - ############################################################################ /api/v1/logs/fail2ban: - get: + get: tags: - Logs - summary: Get latest fail2ban logs. + summary: Get latest Fail2Ban logs. operationId: get-logs-fail2ban - parameters: + parameters: - in: query name: limit schema: @@ -615,4 +640,4 @@ paths: description: "Number of lines displayed (Default: 25)." responses: 200: - description: Success \ No newline at end of file + description: Success