MT-20326: Fix differences between old and new api docs#13
Conversation
📝 WalkthroughWalkthroughOpenAPI specs updated: email schemas adopt required-field wrapper variants (EmailSubjectRequired, EmailTextRequired, EmailHtmlRequired, TemplateUuidRequired); composite email schemas reference these variants and drop top-level required blocks. Suppressions endpoint gains Changes
Sequence Diagram(s)Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📜 Recent review detailsConfiguration used: defaults Review profile: CHILL Plan: Pro 📒 Files selected for processing (6)
💤 Files with no reviewable changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
🧰 Additional context used📓 Path-based instructions (1)specs/**/*.openapi.yml📄 CodeRabbit inference engine (CLAUDE.md)
Files:
🧠 Learnings (3)📓 Common learnings📚 Learning: 2025-12-23T11:20:58.573ZApplied to files:
📚 Learning: 2025-12-29T15:56:56.076ZApplied to files:
🔇 Additional comments (12)
✏️ Tip: You can disable this entire section by setting 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
🤖 Fix all issues with AI agents
In `@specs/email-api.openapi.yml`:
- Around line 825-838: The `end_date` parameter description is incorrect and the
two parameter names are inconsistent: change the `end_date` description to
"Search emails suppressed before this timestamp" (or similar) and pick a
consistent pair of names (either rename `start_time` → `start_date` or
`end_date` → `end_time`) so both use the same suffix; update the parameter names
wherever referenced in the spec and keep the same schema/type/format and
examples (e.g., '2025-12-31T23:59:59Z') to match the chosen naming convention.
In `@specs/sandbox.openapi.yml`:
- Around line 5259-5264: The EmailSender schema currently declares required: -
from which forces every item in BatchEmailRequests (which includes EmailSender
via allOf) to require from; fix by creating a new wrapper schema
EmailSenderRequired that $ref's Address and sets required: [from], leave the
existing EmailSender schema without the required constraint, and update the
top-level composite send schemas (EmailWithText, EmailWithHtml,
EmailWithTextAndHtml, EmailFromTemplate) to reference EmailSenderRequired
instead of EmailSender so individual batch items still inherit from 'base' while
single-send schemas enforce the from field.
🧹 Nitpick comments (3)
specs/email-sending-bulk.openapi.yml (1)
298-314: Address pipeline warnings: unused base schemas.The linter flags
EmailSubject,EmailText,EmailHtml, andTemplateUuidas unused components since only the*Requiredvariants are now referenced by the composite schemas.Options to resolve:
- Remove unused schemas if they serve no external purpose
- Keep for backward compatibility if external tools/clients reference them directly, but add a comment explaining their purpose
Option 1: Remove unused EmailSubject schema
- EmailSubject: - type: object - properties: - subject: - type: string - minLength: 1 - example: Monthly Newsletter - EmailSubjectRequired: type: object required: - subjectApply similar removal to
EmailText,EmailHtml, andTemplateUuidif they are not needed.specs/email-sending-transactional.openapi.yml (1)
272-288: Same unused component warnings apply here.As with the bulk spec, the linter flags
EmailSubject,EmailText,EmailHtml, andTemplateUuidas unused. Apply the same resolution strategy across both specs for consistency.specs/sandbox.openapi.yml (1)
4704-4705: Remove unusedInboxschema alias to resolve pipeline warning.The
Inboxschema is an alias toTestingInboxbut is never referenced. The linter correctly flags it as unused. Consider removing it to clean up the spec.♻️ Proposed fix
components: schemas: - Inbox: - $ref: '#/components/schemas/TestingInbox' InboxMessageWithoutBlacklistsReportInfo:
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
specs/email-api.openapi.ymlspecs/email-sending-bulk.openapi.ymlspecs/email-sending-transactional.openapi.ymlspecs/sandbox.openapi.ymlspecs/webhooks.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/webhooks.openapi.ymlspecs/email-sending-bulk.openapi.ymlspecs/sandbox.openapi.ymlspecs/email-api.openapi.ymlspecs/email-sending-transactional.openapi.yml
🧠 Learnings (5)
📓 Common learnings
Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T11:20:58.573Z
Learning: Applies to specs/**/*.openapi.yml : Update contact URLs in spec `info` blocks to use `https://docs.mailtrap.io`, not help.mailtrap.io
Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T11:20:58.573Z
Learning: Applies to specs/**/*.openapi.yml : 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')
📚 Learning: 2025-12-23T11:20:58.573Z
Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T11:20:58.573Z
Learning: Applies to specs/**/*.openapi.yml : Structure tags with `x-page-title`, `x-page-description`, and `x-parent` for GitBook nested navigation in OpenAPI specs
Applied to files:
specs/webhooks.openapi.yml
📚 Learning: 2025-12-23T11:20:58.573Z
Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T11:20:58.573Z
Learning: Applies to specs/**/*.openapi.yml : 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')
Applied to files:
specs/webhooks.openapi.ymlspecs/email-sending-bulk.openapi.ymlspecs/sandbox.openapi.ymlspecs/email-sending-transactional.openapi.yml
📚 Learning: 2025-12-23T11:20:58.573Z
Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T11:20:58.573Z
Learning: Applies to specs/**/*.openapi.yml : Keep OpenAPI descriptions concise and developer-focused, with technical accuracy prioritized
Applied to files:
specs/webhooks.openapi.yml
📚 Learning: 2025-12-29T15:56:56.076Z
Learnt from: dr-3lo
Repo: mailtrap/mailtrap-openapi PR: 9
File: specs/email-sending-bulk.openapi.yml:159-170
Timestamp: 2025-12-29T15:56:56.076Z
Learning: In OpenAPI spec files under specs, particularly within x-codeSamples code examples, replace actual environment variable references with clear placeholders (e.g., YOUR_API_KEY, YOUR_ACCOUNT_ID) to avoid leaking secrets in documentation. Ensure code samples show substitute values and note how users should provide real values in their environment.
Applied to files:
specs/webhooks.openapi.ymlspecs/email-sending-bulk.openapi.ymlspecs/sandbox.openapi.ymlspecs/email-api.openapi.ymlspecs/email-sending-transactional.openapi.yml
🪛 GitHub Actions: Lint OpenAPI Specs
specs/email-sending-bulk.openapi.yml
[warning] 298-298: oas3-unused-component Potentially unused component has been detected. components.schemas.EmailSubject
[warning] 316-316: oas3-unused-component Potentially unused component has been detected. components.schemas.EmailText
[warning] 334-334: oas3-unused-component Potentially unused component has been detected. components.schemas.EmailHtml
[warning] 413-413: oas3-unused-component Potentially unused component has been detected. components.schemas.TemplateUuid
specs/sandbox.openapi.yml
[warning] 4704-4704: oas3-unused-component Potentially unused component has been detected. components.schemas.Inbox
[error] 5113-5113: "0" property must have required property "from" components.schemas.BatchEmail.example.requests[0]
specs/email-sending-transactional.openapi.yml
[warning] 272-272: oas3-unused-component Potentially unused component has been detected. components.schemas.EmailSubject
[warning] 290-290: oas3-unused-component Potentially unused component has been detected. components.schemas.EmailText
[warning] 308-308: oas3-unused-component Potentially unused component has been detected. components.schemas.EmailHtml
[warning] 387-387: oas3-unused-component Potentially unused component has been detected. components.schemas.TemplateUuid
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Lint OpenAPI files with Spectral
🔇 Additional comments (10)
specs/webhooks.openapi.yml (1)
74-91: LGTM! Improved page titles for webhook handlers.The updated
x-page-titlevalues ("Receive events (JSON format)" and "Receive events (JSON Lines format)") are more descriptive and action-oriented compared to the previous generic "JSON Handler" / "JSON Lines Handler" names. This improves discoverability in the documentation navigation.specs/email-api.openapi.yml (2)
666-666: LGTM! Improved terminology.The change from "Suppressed emails" to "Suppressed addresses" is more accurate since suppression applies to email addresses, not individual email messages.
842-849: LGTM! New error responses added.The addition of 400 (BAD_REQUEST) and 429 (LIMIT_EXCEEDED) responses aligns with the stats endpoints in the same file and improves API consistency.
specs/email-sending-bulk.openapi.yml (1)
443-494: LGTM! Composite schemas correctly reference required variants.The update to reference
EmailSubjectRequired,EmailTextRequired,EmailHtmlRequired, andTemplateUuidRequiredin the composite schemas (EmailWithText,EmailWithHtml,EmailWithTextAndHtml,EmailFromTemplate) properly enforces required field validation through the schema composition. This approach correctly addresses the PR objective of fixing optional/required fields in oneOf schemas.specs/email-sending-transactional.openapi.yml (1)
417-467: LGTM! Consistent with bulk spec changes.The composite schema updates mirror the bulk spec changes, ensuring consistent required field validation across both transactional and bulk email sending endpoints.
specs/sandbox.openapi.yml (5)
4888-4899: LGTM!The
EmailWithTextschema correctly referencesEmailSubjectRequiredandEmailTextRequiredwhile keepingEmailHtmloptional. The title "Text Only" improves documentation clarity.
4930-4941: LGTM!The
EmailWithHtmlschema correctly requires subject and html via wrapper schemas while keeping text optional.
4972-4983: LGTM!The
EmailWithTextAndHtmlschema correctly requires subject, text, and html via the new wrapper schemas.
5015-5053: LGTM!The
EmailFromTemplateschema correctly referencesTemplateUuidRequiredfor template-based emails.
5225-5233: LGTM!The new
*Requiredwrapper schemas follow a consistent pattern, properly marking individual fields as required while preserving the optional variants for batch email contexts.Also applies to: 5281-5289, 5299-5307, 5359-5371
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
mklocek
force-pushed
the
MT-20326-differences-between-old-and-new-api-docs
branch
from
7825d9c to
98026cd
Compare
| ContactCreateRequest: | ||
| $ref: '#/components/schemas/ContactCreateRequest_2' | ||
| ContactList: | ||
| $ref: '#/components/schemas/ContactList_2' |
There was a problem hiding this comment.
These were unused, linter reported it in https://github.com/mailtrap/mailtrap-openapi/actions/runs/21037163013/job/60488205224
… in transactional, bulk & sandbox send endpoints
mklocek
force-pushed
the
MT-20326-differences-between-old-and-new-api-docs
branch
from
98026cd to
31accd5
Compare
4 participants
Motivation
https://railsware.atlassian.net/browse/MT-20326
Changes
How to test
Images and GIFs
None
Summary by CodeRabbit
New Features
Improvements
Breaking Changes
✏️ Tip: You can customize this high-level summary in your review settings.