Skip to content

MT-21122: updated responces #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
GannaRW wants to merge 4 commits into
base: main
Choose a base branch
from
Open

MT-21122: updated responces #35

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
55d6c75
MT-21122: updated responces
GannaRW May 4, 2026
86b3906
MT-21122: updated examples for 422
GannaRW May 6, 2026
a2ed7bc
Fix some wording on email sending openapi
DagonWat May 7, 2026
bedc607
Fix openapi endpoints errors
DagonWat May 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 68 additions & 39 deletions specs/account-management.openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -673,45 +673,28 @@ paths:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
type:
type: string
access_level:
type: integer
resources:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
type:
type: string
access_level:
type: integer
resources:
type: array
items:
nullable: true
type: object
$ref: '#/components/schemas/PermissionResourceNode'
example:
- id: 4001
name: My First Project
type: project
access_level: 1
- id: 1774100
name: Account
type: account
access_level: 100
resources:
- id: 3816
name: My First Inbox
type: inbox
- id: 1774100
name: Templates
type: email_template_permission_scope
access_level: 100
resources: []
- id: 2550469
name: My Project
type: project
access_level: 100
resources:
- id: 4117907
name: My Inbox
type: inbox
access_level: 100
resources: []
'401':
$ref: '#/components/responses/UNAUTHENTICATED'
'403':
Expand Down Expand Up @@ -1061,7 +1044,13 @@ paths:
'401':
$ref: '#/components/responses/UNAUTHENTICATED'
'403':
$ref: '#/components/responses/PERMISSION_DENIED'
description: Insufficient organization permissions or wrong organization.
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionsDeniedResponse'
example:
errors: Access forbidden
post:
operationId: createOrganizationSubAccount
summary: Create organization sub account
Expand Down Expand Up @@ -1117,7 +1106,13 @@ paths:
'401':
$ref: '#/components/responses/UNAUTHENTICATED'
'403':
$ref: '#/components/responses/PERMISSION_DENIED'
description: Insufficient organization permissions or wrong organization.
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionsDeniedResponse'
example:
errors: Access forbidden
'422':
description: Unprocessable entity - validation errors.
content:
Expand All @@ -1141,6 +1136,25 @@ components:
type: string
example: Development Team Account
description: The name of the sub account
PermissionResourceNode:
title: Permission resource node
description: |
Nested resource tree for permission management. `type` values include `account`, `project`, `inbox`,
`sending_domain`, `email_template_permission_scope`, `email_campaign_permission_scope`, and others.
type: object
properties:
id:
type: integer
name:
type: string
type:
type: string
access_level:
type: integer
resources:
type: array
items:
$ref: '#/components/schemas/PermissionResourceNode'
AccountAccess:
title: AccountAccess
description: Assigns resource-specific permissions to a specifier.
Expand Down Expand Up @@ -1220,6 +1234,7 @@ components:
enum:
- account
- billing
- organization
- project
- inbox
- sending_domain
Expand Down Expand Up @@ -1259,14 +1274,20 @@ components:
type: string
description: Error message
example: Not Found
example:
error: Not Found
PermissionsDeniedResponse:
title: PermissionsDeniedResponse
type: object
properties:
errors:
type: string
description: Error message
example: Access forbidden
description: |
Human-readable reason. Common values include `Account access forbidden` (e.g. wrong account)
and `Access forbidden` (e.g. insufficient rights on an organization).
example: Account access forbidden
example:
errors: Account access forbidden
UnauthenticatedResponse:
title: UnauthenticatedResponse
type: object
Expand All @@ -1275,6 +1296,8 @@ components:
type: string
description: Error message
example: Incorrect API token
example:
error: Incorrect API token
ErrorResponse:
title: ErrorResponse
type: object
Expand Down Expand Up @@ -1459,18 +1482,24 @@ components:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedResponse'
example:
error: Incorrect API token
PERMISSION_DENIED:
description: Returns forbidden error message. Check your permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionsDeniedResponse'
example:
errors: Account access forbidden
NOT_FOUND:
description: Returns not found error message
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
example:
error: Not Found
UNPROCESSABLE_ENTITY:
description: Validation error or other business rule violation
content:
Expand Down
41 changes: 35 additions & 6 deletions specs/contacts.openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -643,7 +643,14 @@ paths:
'403':
$ref: '#/components/responses/PERMISSION_DENIED'
'404':
$ref: '#/components/responses/NOT_FOUND'
description: |-
No contact for the given identifier. The JSON body uses an `errors` string (not the `error` key used by some other 404 responses).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
errors: Contact(s) not found
'429':
$ref: '#/components/responses/LIMIT_EXCEEDED'
'500':
Expand Down Expand Up @@ -1787,15 +1794,15 @@ paths:
example:
- id: 6730
name: First name
type: text
data_type: text
merge_tag: first_name
- id: 6731
name: Birthdate
type: date
data_type: date
merge_tag: birthdate
- id: 6732
name: Cats count
type: integer
data_type: integer
merge_tag: cats_count
'401':
$ref: '#/components/responses/UNAUTHENTICATED'
Expand Down Expand Up @@ -2735,6 +2742,8 @@ components:
type: string
description: Error message
example: Unexpected error
example:
errors: Unexpected error
NotFoundResponse:
title: NotFoundResponse
type: object
Expand All @@ -2743,14 +2752,20 @@ components:
type: string
description: Error message
example: Not Found
example:
error: Not Found
PermissionsDeniedResponse:
title: PermissionsDeniedResponse
type: object
properties:
errors:
type: string
description: Error message
example: Access forbidden
description: |
Human-readable reason. Common values include `Account access forbidden` (e.g. wrong account)
and `Access forbidden` when the token lacks rights for the operation.
example: Account access forbidden
example:
errors: Account access forbidden
RateLimitExceededResponse:
title: RateLimitExceededResponse
type: object
Expand All @@ -2759,6 +2774,8 @@ components:
type: string
description: Error message
example: Rate limit exceeded
example:
errors: Rate limit exceeded
UnauthenticatedResponse:
title: UnauthenticatedResponse
type: object
Expand All @@ -2767,6 +2784,8 @@ components:
type: string
description: Error message
example: Incorrect API token
example:
error: Incorrect API token
UnprocessableEntity:
title: UnprocessableEntity
type: object
Expand All @@ -2782,30 +2801,40 @@ components:
application/json:
schema:
$ref: '#/components/schemas/UnauthenticatedResponse'
example:
error: Incorrect API token
LIMIT_EXCEEDED:
description: Rate limit exceeded for the current account.
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitExceededResponse'
example:
errors: Rate limit exceeded
PERMISSION_DENIED:
description: Returns forbidden error message. Check your permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionsDeniedResponse'
example:
errors: Account access forbidden
INTERNAL_ERROR:
description: Internal error. Retry later or contact support.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
errors: Unexpected error
NOT_FOUND:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
example:
error: Not Found
parameters:
account_id:
description: Unique account ID
Expand Down
26 changes: 23 additions & 3 deletions specs/email-sending-bulk.openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,9 @@ info:
url: 'https://mailtrap.io/wp-content/uploads/2021/04/mailtrap-logo.svg'

servers:
- description: Bulk Stream
- description: |
Bulk Stream. Use a normal HTTP client `User-Agent` (as typical browsers and `curl` do); bare
requests without one may be blocked by edge protection.
url: 'https://bulk.api.mailtrap.io'

security:
Expand Down Expand Up @@ -741,6 +743,9 @@ components:

SendEmailErrorResponse:
type: object
description: |
Error responses from the sending API use `success: false` and an `errors` array of strings
(unlike account APIs on `mailtrap.io`, which use `error` or a single `errors` string).
properties:
success:
type: boolean
Expand All @@ -750,6 +755,10 @@ components:
items:
type: string
example: Invalid sender email address
example:
success: false
errors:
- "'from' address is invalid"

BatchEmail:
title: Batch Email Request
Expand Down Expand Up @@ -832,7 +841,10 @@ components:
example:
success: false
errors:
- "'from' address is invalid"
- "'from' is required"
- "'to', 'cc' or 'bcc' address is required"
- "'subject' is required"
- must specify either text or html body

Unauthorized:
description: Unauthorized. Check your API credentials.
Expand All @@ -843,18 +855,26 @@ components:
example:
success: false
errors:
- "Unauthorized"
- Unauthorized

Forbidden:
description: Forbidden. Verify domain or check permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailErrorResponse'
example:
success: false
errors:
- Forbidden

InternalError:
description: Internal server error. Retry later or contact support.
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailErrorResponse'
example:
success: false
errors:
- Internal server error
Loading
Loading