Update suppressions API spec#32
Open
VladimirTaytor wants to merge 4 commits intomainfrom
Open
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughOpenAPI spec updates for the suppressions endpoints: list gains cursor pagination ( ChangesSuppressions API spec updates
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 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: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
specs/email-sending.openapi.yml (1)
1203-1204:⚠️ Potential issue | 🟡 MinorDELETE code samples still use a non-UUID placeholder for
suppression_id.Now that
suppression_idis typed asstring/format: uuid(lines 1678–1680), the literal"abc123-def456"used across the DELETE samples is not a valid UUID and may confuse readers or break copy-paste-style validators. Consider using the same example UUID already present elsewhere (e.g.64d71bf3-1276-417b-86e1-8e66f138acfe).✏️ Example fix (apply to each language sample)
- const suppressionId = "abc123-def456"; + const suppressionId = "64d71bf3-1276-417b-86e1-8e66f138acfe";- $suppressionId = 'abc123-def456'; + $suppressionId = '64d71bf3-1276-417b-86e1-8e66f138acfe';- suppression_id = "abc123-def456" + suppression_id = "64d71bf3-1276-417b-86e1-8e66f138acfe"- suppression_id = 'abc123-def456' + suppression_id = '64d71bf3-1276-417b-86e1-8e66f138acfe'- var suppressionId = "abc123-def456"; + var suppressionId = "64d71bf3-1276-417b-86e1-8e66f138acfe";- String suppressionId = "abc123-def456"; + String suppressionId = "64d71bf3-1276-417b-86e1-8e66f138acfe";Also applies to: 1223-1223, 1236-1236, 1251-1251, 1263-1263, 1282-1282
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@specs/email-sending.openapi.yml` around lines 1203 - 1204, Replace the invalid non-UUID placeholder used for suppressionId with a valid example UUID across all DELETE code samples; specifically update the variable assignment (e.g., const suppressionId = "64d71bf3-1276-417b-86e1-8e66f138acfe") used before calling client.suppressions.delete(suppressionId) so it matches the suppression_id schema (string, format: uuid) and apply the same replacement to the other listed samples (lines referenced in the review).
🧹 Nitpick comments (1)
specs/email-sending.openapi.yml (1)
2126-2174: Consider adding a top-levelexampleto theSuppressionschema.Sister schemas (
SendingDomain,CompanyInfo,EmailLogsListResponse,SendingMessage, …) all carry anexampleblock. With the substantial reshape here (UUID id, newtype,sending_stream,domain_name, tenmessage_*nullable fields), an example would make the GitBook preview and SDK docs much easier to read and would also serve as a sanity check that the field set is internally consistent.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@specs/email-sending.openapi.yml` around lines 2126 - 2174, Add a top-level example object to the Suppression schema that demonstrates valid values for id, type, created_at, email, sending_stream, domain_name and the nullable message_* fields (either realistic strings or null where appropriate) so the OpenAPI/GitBook preview and generated SDK docs show a complete, internally consistent suppression record; update the Suppression schema's YAML to include an example block with representative values (e.g., UUID for id, one of the enum values for type and sending_stream, RFC3339 timestamp for created_at, a sample email, and either plausible strings or nulls for message_bounce_category, message_category, message_client_ip, message_created_at, message_esp_response, message_esp_server_type, message_outgoing_ip, message_recipient_mx_name, message_sender_email, and message_subject).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@specs/email-sending.openapi.yml`:
- Around line 1157-1162: The request body defines the suppression reason as the
field named "reason" while the response schema "Suppression" uses "type"; align
these by renaming the response schema's "type" property to "reason" (or
alternatively rename the request property to "type" if you prefer that canonical
name), update the enum, default, description and example to use the chosen name,
and ensure both the POST request body and the Suppression response schema
reference the identical property name and matching description so there is no
naming inconsistency.
---
Outside diff comments:
In `@specs/email-sending.openapi.yml`:
- Around line 1203-1204: Replace the invalid non-UUID placeholder used for
suppressionId with a valid example UUID across all DELETE code samples;
specifically update the variable assignment (e.g., const suppressionId =
"64d71bf3-1276-417b-86e1-8e66f138acfe") used before calling
client.suppressions.delete(suppressionId) so it matches the suppression_id
schema (string, format: uuid) and apply the same replacement to the other listed
samples (lines referenced in the review).
---
Nitpick comments:
In `@specs/email-sending.openapi.yml`:
- Around line 2126-2174: Add a top-level example object to the Suppression
schema that demonstrates valid values for id, type, created_at, email,
sending_stream, domain_name and the nullable message_* fields (either realistic
strings or null where appropriate) so the OpenAPI/GitBook preview and generated
SDK docs show a complete, internally consistent suppression record; update the
Suppression schema's YAML to include an example block with representative values
(e.g., UUID for id, one of the enum values for type and sending_stream, RFC3339
timestamp for created_at, a sample email, and either plausible strings or nulls
for message_bounce_category, message_category, message_client_ip,
message_created_at, message_esp_response, message_esp_server_type,
message_outgoing_ip, message_recipient_mx_name, message_sender_email, and
message_subject).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b30482de-f75b-49ef-8193-56fc0d55b071
📒 Files selected for processing (1)
specs/email-sending.openapi.yml
VladimirTaytor
force-pushed
the
update-suppressions-api
branch
from
827a7b3 to
81c8394
Compare
Aligns the create request body field name with the response field name. Falcon-side change: railsware/falcon#10169 (MT-21943).
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@specs/email-sending.openapi.yml`:
- Around line 1108-1120: The POST suppression endpoint's x-codeSamples currently
only contains a cURL example; add the missing six language-specific samples in
the required priority order (shell/cURL, Node.js (JavaScript), PHP, Python,
Ruby, .NET (C#), Java) under the same x-codeSamples array for the POST operation
so the docs render all tabs; for each language use the official Mailtrap SDK
snippet invoking the suppressions create/send method (or the closest SDK method)
and if an SDK lacks the exact method, include a generated HTTP example or a
short comment noting the SDK limitation per guidelines.
- Around line 3075-3090: The CreateSuppressionResponse and
DeleteSuppressionResponse shapes are inconsistent: CreateSuppressionResponse
nests the Suppression under data while DeleteSuppressionResponse returns the
Suppression directly; confirm the backend and then make the spec consistent by
choosing one of two fixes — Option A: wrap DeleteSuppressionResponse to match
CreateSuppressionResponse by changing DeleteSuppressionResponse content schema
to an object with a data property that $ref:s the Suppression schema (same shape
as CreateSuppressionResponse), or Option B: unwrap CreateSuppressionResponse to
match DeleteSuppressionResponse and GetSuppressionsResponse by replacing its
object-with-data schema with a direct $ref to the Suppression schema; update the
components for CreateSuppressionResponse and DeleteSuppressionResponse in
specs/email-sending.openapi.yml accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 15a1723c-d571-43aa-9a96-abb810f58c41
📒 Files selected for processing (1)
specs/email-sending.openapi.yml
Resolve conflict in specs/email-sending.openapi.yml: keep new
createSuppression POST operation; adopt main's account-scoped
DELETE path /api/accounts/{account_id}/suppressions/{suppression_id};
update POST cURL example to use the account-scoped URL.
VladimirTaytor
commented
May 5, 2026
| type: string | ||
| format: email | ||
| example: suppressed@example.com | ||
| reason: |
Contributor
Author
There was a problem hiding this comment.
Actually it was a mistake we never had reason here filed should be named type and all SDKs support type
piobeny
approved these changes
May 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Update
specs/email-sending.openapi.ymlto reflect Suppressions API changes (newPOSTendpoint, cursor pagination, admin-only access) and fix pre-existing schema inaccuracies that did not match the actual API responses.Changes
GET /api/suppressions— addedlast_idcursor pagination query param; clarified parameter descriptions; noted 10 rpm rate limitPOST /api/suppressions— new endpoint (admin-only, 10 rpm); body:email,domain_id,sending_stream, optionaltype(defaults tomanual import)DELETE /api/suppressions/{suppression_id}— added admin-only notesuppression_idpath parameter:integer→string/uuidSuppressionschema:idis now a uuid string;reasonfield renamed totypewith values[hard bounce, unsubscription, spam complaint, manual import]; addedsending_stream,domain_name, and ten nullablemessage_*fieldsDeleteSuppressionResponsenow referencesSuppression(previously a{success, message}shape that did not match the API)CreateSuppressionResponsewrappingSuppressionin adatakeyHow to test
POSTendpoint and updatedSuppressionschema correctlydomain_id(integer) matches the public API implementationSummary by CodeRabbit