MT-23420: document the delete organization sub account endpoint

specs/account-management.openapi.yml

@@ -1701,6 +1701,119 @@ paths:
                 $ref: '#/components/schemas/UnprocessableEntity'
     parameters:
       - $ref: '#/components/parameters/organization_id'
+  '/api/organizations/{organization_id}/sub_accounts/{sub_account_id}':
+    delete:
+      operationId: deleteOrganizationSubAccount
+      summary: Delete organization sub account
+      description: |-
+        Delete a sub account of the specified organization. You must have sub account management
+        permissions for this organization.
+
+        The sub account and all of its data – projects, sandboxes, emails and domains – are removed
+        permanently and cannot be restored. Deleting the organization's last sub account also deletes
+        the organization.
+
+        A repeated call for the same sub account returns `404`, because a sub account that is already
+        scheduled for deletion is no longer listed.
+
+        Rate limit: 10 requests per minute per organization.
+      tags:
+        - Organizations
+      x-codeSamples:
+        - lang: shell
+          label: 'cURL'
+          source: |
+            curl -X DELETE https://mailtrap.io/api/organizations/{organization_id}/sub_accounts/{sub_account_id} \
+              -H 'Authorization: Bearer YOUR_API_KEY'
+        - lang: javascript
+          label: Node.js
+          source: |
+            import { MailtrapClient } from "mailtrap";
+
+            const organizationId = 2000002;
+            const client = new MailtrapClient({ token: "YOUR_API_KEY", organizationId });
+
+            const subAccountId = 12347;
+            await client.organizations.subAccounts.delete(subAccountId);
+        - lang: php
+          label: PHP
+          source: |
+            <?php
+            use Mailtrap\Config;
+            use Mailtrap\MailtrapGeneralClient;
+
+            $config = new Config($_ENV['MAILTRAP_API_KEY']);
+            $organizationId = $_ENV['MAILTRAP_ORGANIZATION_ID'];
+            $subAccounts = (new MailtrapGeneralClient($config))->organization($organizationId)->subAccounts();
+
+            $subAccountId = $_ENV['MAILTRAP_SUB_ACCOUNT_ID'];
+            $response = $subAccounts->deleteSubAccount($subAccountId);
+            echo $response->getStatusCode(); // 204
+        - lang: python
+          label: Python
+          source: |
+            import mailtrap as mt
+
+            organization_id = 2000002
+            client = mt.MailtrapClient(token="YOUR_API_KEY", organization_id=organization_id)
+
+            sub_account_id = 12347
+            client.organizations_api.sub_accounts.delete(sub_account_id)
+        - lang: ruby
+          label: Ruby
+          source: |
+            require 'mailtrap'
+
+            client = Mailtrap::Client.new(api_key: 'YOUR_API_KEY')
+            organization_id = 2000002
+            sub_accounts = Mailtrap::SubAccountsAPI.new(organization_id, client)
+
+            sub_account_id = 12347
+            sub_accounts.delete(sub_account_id)
+        - lang: csharp
+          label: .NET
+          source: |
+            using Mailtrap;
+
+            using var mailtrapFactory = new MailtrapClientFactory("YOUR_API_KEY");
+            // Sub-accounts live under /organizations/{id}, so use the organization client.
+            var client = mailtrapFactory.CreateOrganizationClient();
+
+            var organizationId = 2000002;
+            var subAccountId = 12347;
+            await client.Organization(organizationId).SubAccount(subAccountId).Delete();
+        - lang: java
+          label: Java
+          source: |
+            import io.mailtrap.config.MailtrapConfig;
+            import io.mailtrap.factory.MailtrapClientFactory;
+
+            var config = new MailtrapConfig.Builder().token("YOUR_API_KEY").build();
+            var client = MailtrapClientFactory.createMailtrapClient(config);
+
+            long organizationId = 2000002L;
+            long subAccountId = 12347L;
+            client.organizationsApi().subAccounts().deleteSubAccount(organizationId, subAccountId);
+      responses:
+        '204':
+          description: Sub account deleted successfully. No content is returned.
+        '401':
+          $ref: '#/components/responses/UNAUTHENTICATED'
+        '403':
+          description: Insufficient organization permissions or wrong organization.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PermissionsDeniedResponse'
+              example:
+                errors: Access forbidden
+        '404':
+          $ref: '#/components/responses/NOT_FOUND'
+        '429':
+          $ref: '#/components/responses/LIMIT_EXCEEDED'
+    parameters:
+      - $ref: '#/components/parameters/organization_id'
+      - $ref: '#/components/parameters/sub_account_id'
 components:
   schemas:
     SubAccount:
@@ -1865,6 +1978,16 @@ components:
           example: Account access forbidden
       example:
         errors: Account access forbidden
+    RateLimitExceededResponse:
+      title: RateLimitExceededResponse
+      type: object
+      properties:
+        errors:
+          type: string
+          description: Error message
+          example: Rate limit exceeded
+      example:
+        errors: Rate limit exceeded
     UnauthenticatedResponse:
       title: UnauthenticatedResponse
       type: object
@@ -2085,13 +2208,31 @@ components:
             $ref: '#/components/schemas/NotFoundResponse'
           example:
             error: Not Found
+    LIMIT_EXCEEDED:
+      description: Rate limit exceeded.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/RateLimitExceededResponse'
+          example:
+            errors: Rate limit exceeded
     UNPROCESSABLE_ENTITY:
       description: Validation error or other business rule violation
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/UnprocessableEntity'
   parameters:
+    sub_account_id:
+      description: Unique sub account ID
+      name: sub_account_id
+      in: path
+      required: true
+      schema:
+        type: integer
+        format: int64
+        minimum: 1
+        example: 12345
     organization_id:
       description: Unique organization ID
       name: organization_id