From a674d79140d7ba465856d3c4d13cda7f94963b64 Mon Sep 17 00:00:00 2001 From: Alex Shchyhol Date: Mon, 24 Aug 2026 11:25:24 +0200 Subject: [PATCH 1/5] document the delete organization sub account endpoint --- specs/account-management.openapi.yml | 72 ++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/specs/account-management.openapi.yml b/specs/account-management.openapi.yml index 72b805c..7b2245b 100644 --- a/specs/account-management.openapi.yml +++ b/specs/account-management.openapi.yml @@ -1701,6 +1701,50 @@ 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_TOKEN' + 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 +1909,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,6 +2139,14 @@ 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: @@ -2092,6 +2154,16 @@ components: 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 From bb831d14f9bf6d97e579ee1eca32b72ce4fa878d Mon Sep 17 00:00:00 2001 From: Alex Shchyhol Date: Tue, 8 Sep 2026 10:59:19 +0200 Subject: [PATCH 2/5] add SDK code samples for deleteOrganizationSubAccount --- specs/account-management.openapi.yml | 71 +++++++++++++++++++++++++++- 1 file changed, 70 insertions(+), 1 deletion(-) diff --git a/specs/account-management.openapi.yml b/specs/account-management.openapi.yml index 7b2245b..29a2d68 100644 --- a/specs/account-management.openapi.yml +++ b/specs/account-management.openapi.yml @@ -1724,7 +1724,76 @@ paths: label: 'cURL' source: | curl -X DELETE https://mailtrap.io/api/organizations/{organization_id}/sub_accounts/{sub_account_id} \ - -H 'Authorization: Bearer YOUR_API_TOKEN' + -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: | + 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. From 0f10a39a5c17a3a0b3e6c1225e7cb737a5f394c7 Mon Sep 17 00:00:00 2001 From: Alex Shchyhol Date: Fri, 11 Sep 2026 12:19:10 +0200 Subject: [PATCH 3/5] document the organization feature requirement for deleting a sub account --- specs/account-management.openapi.yml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/specs/account-management.openapi.yml b/specs/account-management.openapi.yml index 29a2d68..b0cc265 100644 --- a/specs/account-management.openapi.yml +++ b/specs/account-management.openapi.yml @@ -1707,7 +1707,8 @@ paths: summary: Delete organization sub account description: |- Delete a sub account of the specified organization. You must have sub account management - permissions for this organization. + permissions for this organization, and the organization must have the Organization & + Sub-accounts feature enabled. 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 @@ -1800,7 +1801,9 @@ paths: '401': $ref: '#/components/responses/UNAUTHENTICATED' '403': - description: Insufficient organization permissions or wrong organization. + description: |- + Insufficient organization permissions, wrong organization, or the Organization & + Sub-accounts feature is disabled for this organization. content: application/json: schema: From 28f86aefd8dffd63eeffec72a2f46b632031163f Mon Sep 17 00:00:00 2001 From: Alex Shchyhol Date: Fri, 11 Sep 2026 12:45:54 +0200 Subject: [PATCH 4/5] document the conflict response and drop the redundant 404 note --- specs/account-management.openapi.yml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/specs/account-management.openapi.yml b/specs/account-management.openapi.yml index b0cc265..9dfb590 100644 --- a/specs/account-management.openapi.yml +++ b/specs/account-management.openapi.yml @@ -1714,9 +1714,6 @@ paths: 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 @@ -1812,6 +1809,14 @@ paths: errors: Access forbidden '404': $ref: '#/components/responses/NOT_FOUND' + '409': + description: Another deletion of the same sub account is already in progress. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + example: + errors: Another action in progress. Wait until it's finished '429': $ref: '#/components/responses/LIMIT_EXCEEDED' parameters: From ebd84d98606eb109ef38052595653dd6cb84535c Mon Sep 17 00:00:00 2001 From: Alex Shchyhol Date: Mon, 19 Oct 2026 19:26:54 +0200 Subject: [PATCH 5/5] accept organization access permissions on the sub account endpoints Organization Access Only users and organization API tokens can list, create and delete sub accounts too, so the list, create and delete descriptions name both permissions. --- specs/account-management.openapi.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specs/account-management.openapi.yml b/specs/account-management.openapi.yml index 9dfb590..b5f4f62 100644 --- a/specs/account-management.openapi.yml +++ b/specs/account-management.openapi.yml @@ -1449,7 +1449,7 @@ paths: get: operationId: getOrganizationSubAccounts summary: Get organization sub accounts - description: Get a list of sub accounts for the specified organization. You must have sub account management permissions for this organization. + description: Get a list of sub accounts for the specified organization. You must have sub account management or organization access permissions for this organization. tags: - Organizations x-codeSamples: @@ -1553,7 +1553,7 @@ paths: post: operationId: createOrganizationSubAccount summary: Create organization sub account - description: Create a new sub account under the specified organization. You must have sub account management permissions for this organization. + description: Create a new sub account under the specified organization. You must have sub account management or organization access permissions for this organization. tags: - Organizations x-codeSamples: @@ -1706,9 +1706,9 @@ paths: 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, and the organization must have the Organization & - Sub-accounts feature enabled. + Delete a sub account of the specified organization. You must have sub account management or + organization access permissions for this organization, and the organization must have the + Organization & Sub-accounts feature enabled. 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