document the delete organization sub account endpoint

[oshchyhol]

Motivation

Sub-accounts can now be deleted from the organization panel, and the same action is exposed over
the public API. DELETE /api/organizations/{organization_id}/sub_accounts/{sub_account_id} is not
described in the spec yet, so it is missing from the rendered reference.

Changes

• deleteOrganizationSubAccount: new delete operation on
  /api/organizations/{organization_id}/sub_accounts/{sub_account_id}, tagged Organizations,
  reusing the existing organization_id and sub_account_id parameters
  • 204 with no body on success, 401, 403 on insufficient organization permissions or a
    sub-account outside the organization, 404 on an unknown or already deleted sub-account,
    409 when a deletion for the same sub-account is already running, 429 over the rate limit of
    10 requests per minute per organization
  • the description states that the sub-account and its data are removed permanently, and that
    deleting the organization's last sub-account also deletes the organization
  • code samples for cURL, Node.js, PHP, Python, Ruby, .NET and Java, mirroring the create
    operation; the SDK methods land in the companion PRs below
• new RateLimitExceededResponse schema and LIMIT_EXCEEDED response for the 429, which the
  spec had no shared definition for

How to test

• the spec lints clean in CI
• in the rendered reference, Organizations shows "Delete organization sub account" with the
  organization_id and sub_account_id path params, cURL / Node.js / PHP / Python / Ruby /
  .NET / Java samples, and 204/401/403/404/409/429 responses
• the 429 example reads {"errors": "Rate limit exceeded"}
• against the deployed API: DELETE /api/organizations/:organization_id/sub_accounts/:id with
  a token holding Sub-accounts Creation & Listing Admin returns 204 and the sub-account is gone
  from GET /api/organizations/:organization_id/sub_accounts
• the same call repeated returns 404; with a viewer-level token 403; with no token 401
• a second DELETE for the same sub-account while the first one is still in flight returns 409
  with {"errors": "Another action in progress. Wait until it's finished"}
• more than 10 calls within a minute for one organization return 429

Companion PRs

• backend endpoint (must deploy first)
• add sub account deletion mailtrap-nodejs#159 – nodejs SDK
• add sub account deletion mailtrap-ruby#130 – ruby SDK
• add sub account deletion mailtrap-python#83 – python SDK
• add sub account deletion mailtrap-php#80 – php SDK
• add sub account deletion mailtrap-java#75 – java SDK
• add sub account deletion mailtrap-dotnet#259 – .NET SDK
• add sub account deletion mailtrap-go#30 – go SDK
• add sub-account deletion to the CLI mailtrap-cli#15 – CLI
• add delete-sub-account tool mailtrap-mcp#144 – MCP server

Caveat: merge after the backend change ships – the endpoint does not exist in production yet. The
documented last-sub-account behaviour is inherited from the existing deletion flow; if that gets a
guard before release, the description needs updating.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 95c5792c-a85b-49ae-bd23-7291acf9b5bb

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[IgorDobryn]

Is there specific rate limiting in this case?

[oshchyhol]

yes, there is one for this endpoint