MT-20083 Add Public Stats API docs to Gitbook #5
Conversation
|
Caution Review failedThe pull request is closed. 📝 WalkthroughWalkthroughAdds a new "stats" area to the email API OpenAPI spec: five GET endpoints under /api/accounts/{account_id}/stats for aggregated sending statistics, new filtering query parameters, SendingStats/BadRequest/RateLimitExceeded schemas, and BAD_REQUEST/LIMIT_EXCEEDED response mappings. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
📜 Recent review detailsConfiguration used: defaults Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
specs/email-api.openapi.yml (2)
1897-1913: Consider aligning error schema structure with existingErrorResponse.The new
BadRequestandRateLimitExceededResponseschemas useerrorsas a single string, while the existingErrorResponseschema (used by Unauthorized, Forbidden) useserrorsas an array of strings. This inconsistency may confuse API consumers.Option: Align with existing pattern
BadRequest: title: BadRequestResponse type: object properties: errors: - type: string - description: Error message - example: Invalid request parameters + type: array + items: + type: string + description: Error messages + example: + - Invalid request parameters
1960-1972: Inconsistent response naming convention.The new responses
BAD_REQUESTandLIMIT_EXCEEDEDuse SCREAMING_SNAKE_CASE, while existing responses use PascalCase (Unauthorized,Forbidden,NotFound,UnprocessableEntity). Consider renaming for consistency.Proposed fix
- BAD_REQUEST: + BadRequest: description: Bad request - invalid parameters. content: application/json: schema: $ref: '#/components/schemas/BadRequest' - LIMIT_EXCEEDED: + RateLimitExceeded: description: Rate limit exceeded for the current account. content: application/json: schema: $ref: '#/components/schemas/RateLimitExceededResponse'Then update the endpoint references accordingly:
'400': - $ref: '#/components/responses/BAD_REQUEST' + $ref: '#/components/responses/BadRequest' ... '429': - $ref: '#/components/responses/LIMIT_EXCEEDED' + $ref: '#/components/responses/RateLimitExceeded'
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
specs/email-api.openapi.yml
🧰 Additional context used
📓 Path-based instructions (1)
specs/**/*.openapi.yml
📄 CodeRabbit inference engine (CLAUDE.md)
specs/**/*.openapi.yml: Base URLs must never be changed in OpenAPI specs. Usehttps://send.api.mailtrap.iofor transactional emails,https://bulk.api.mailtrap.iofor bulk emails, andhttps://mailtrap.iofor all other APIs
All documentation links in OpenAPI specs must be absolute URLs pointing to docs.mailtrap.io, not relative links or help.mailtrap.io
Update contact URLs in specinfoblocks to usehttps://docs.mailtrap.io, not help.mailtrap.io
Use GitBook markdown syntax in OpenAPI description fields, ensuring all blocks are properly closed:{% hint %}...{% endhint %}and{% tab %}...{% endtab %}
Tabs cannot be nested inside details blocks when using GitBook syntax in OpenAPI descriptions
Include code samples inx-codeSamplesin this priority order: Node.js, PHP, Python, Ruby, .NET, Java, cURL
Use official Mailtrap SDKs for language-specific code samples inx-codeSamples, with Node.js (mailtrap/mailtrap-nodejs), PHP (railsware/mailtrap-php), Python (railsware/mailtrap-python), and Ruby (railsware/mailtrap-ruby)
Use environment variables for API keys in code samples (e.g.,process.env.MAILTRAP_API_KEY)
Validate YAML syntax, OpenAPI 3.1 compliance, base URLs, contact URLs, GitBook blocks, links, and code samples before committing OpenAPI spec changes
Do not use emojis in specification content
Keep OpenAPI descriptions concise and developer-focused, with technical accuracy prioritized
Use custom OpenAPI extensions for GitBook navigation:x-page-title,x-page-icon,x-page-description,x-parent,x-codeSamples, andx-logo
Structure tags withx-page-title,x-page-description, andx-parentfor GitBook nested navigation in OpenAPI specs
Use official product naming: 'Email API/SMTP' (can shorten to 'Email API' or 'API/SMTP'), 'Email Sandbox' (can shorten to 'Sandbox'), 'Email Marketing' (can shorten to 'Marketing')
Files:
specs/email-api.openapi.yml
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T11:20:58.562Z
Learning: Applies to specs/**/*.openapi.yml : Update contact URLs in spec `info` blocks to use `https://docs.mailtrap.io`, not help.mailtrap.io
🔇 Additional comments (3)
specs/email-api.openapi.yml (3)
1442-1454: Verify ifstatsshould be an array or single object.The base
/statsendpoint returns a singleSendingStatsobject, but the grouped endpoints (by domains, categories, etc.) returnstatsas an array. If each group returns aggregated stats, a single object might be more appropriate. If it returns time-series data within each group, the array is correct.
1634-1726: LGTM!The query filter parameters are well-defined with appropriate types, descriptions, and examples. Required date filters and optional grouping filters are a sensible design for a stats API.
1857-1896: LGTM!The
SendingStatsschema is well-structured with clear property names, appropriate types (integerfor counts,doublefor rates), and helpful examples.
| '/api/accounts/{account_id}/stats': | ||
| get: | ||
| operationId: getAccountSendingStats | ||
| summary: Get account sending stats | ||
| description: Get account sending stats. Use filters to get specific stats. | ||
| tags: | ||
| - stats | ||
| parameters: | ||
| - $ref: '#/components/parameters/account_id' | ||
| - $ref: '#/components/parameters/StartDateQueryFilter' | ||
| - $ref: '#/components/parameters/EndDateQueryFilter' | ||
| - $ref: '#/components/parameters/SendingDomainIDsQueryFilter' | ||
| - $ref: '#/components/parameters/SendingStreamsQueryFilter' | ||
| - $ref: '#/components/parameters/CategoriesQueryFilter' | ||
| - $ref: '#/components/parameters/ESPsQueryFilter' | ||
| responses: | ||
| '200': | ||
| description: OK | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/SendingStats' | ||
| '400': | ||
| $ref: '#/components/responses/BAD_REQUEST' | ||
| '401': | ||
| $ref: '#/components/responses/Unauthorized' | ||
| '403': | ||
| $ref: '#/components/responses/Forbidden' | ||
| '429': | ||
| $ref: '#/components/responses/LIMIT_EXCEEDED' | ||
| '/api/accounts/{account_id}/stats/domains': |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Missing x-codeSamples for stats endpoints.
Per coding guidelines, all endpoints should include code samples in priority order: Node.js, PHP, Python, Ruby, .NET, Java, cURL. The stats endpoints currently lack these samples, unlike other endpoints in this spec.
Consider adding code samples using the official Mailtrap SDKs (when supported) or cURL examples at minimum.
🤖 Prompt for AI Agents
In specs/email-api.openapi.yml around lines 1391 to 1421, the GET
/api/accounts/{account_id}/stats operation is missing the required x-codeSamples
section; add an x-codeSamples array under the operation (or under the 200
response) containing prioritized examples: Node.js, PHP, Python, Ruby, .NET,
Java, and cURL; each sample should include a short description, language, and a
runnable snippet showing authorization and the request to this endpoint (prefer
official Mailtrap SDK snippet when available, otherwise provide a concise cURL
example) so the stats endpoint matches the rest of the spec.
|
Btw. I also pushed small updates to Suppressions API in https://github.com/railsware/mailtrap-public-docs/pull/139. They are not QA'd and released yet though. |
IgorDobryn
left a comment
IgorDobryn
left a comment
There was a problem hiding this comment.
Suggestion: ask chatGPT to format title in API style
Motivation:
How to test:
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.