MT-22654: Document tracking opt-outs public API#46
Conversation
Decisions: - Mirror suppressions path style (`/api/tracking_opt_outs`) for account-scoped v2 endpoints - SDK samples deferred until client libraries ship tracking opt-out support Co-authored-by: Cursor <cursoragent@cursor.com>
📝 WalkthroughWalkthroughThe OpenAPI spec adds tracking opt-out documentation, domain setting fields, and new list/create/delete tracking opt-out endpoints with supporting parameters, schemas, and responses. ChangesTracking opt-out OpenAPI additions
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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
🤖 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 1422-1431: The create/delete tracking opt-outs docs only include
cURL, so the standard code sample tabs are missing for these operations. Update
the x-codeSamples blocks in the tracking_opt_outs POST/DELETE sections to follow
the repo’s usual priority order: cURL, Node.js, PHP, Python, Ruby, .NET, and
Java, and include the same explicit “SDK does not yet support tracking opt-outs”
limitation note for the unsupported SDK entries. Use the existing tracking
opt-outs sample patterns in this spec to keep the language ordering and
messaging consistent.
- Around line 1323-1368: The Node.js x-codeSamples entry for tracking opt-outs
mixes a MailtrapClient instantiation with a raw fetch call, which is misleading
because it implies SDK support that does not exist. Update the JavaScript sample
to match the other language blocks by replacing the example in the tracking
opt-outs section with an SDK-limitation note, and remove the
MailtrapClient/getTrackingOptOuts sample so readers are directed to the cURL
example until the SDK supports this endpoint.
🪄 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: 9fc7721e-0a63-4262-ab46-ae21764c1070
📒 Files selected for processing (1)
specs/email-sending.openapi.yml
| - lang: javascript | ||
| label: Node.js | ||
| source: | | ||
| import { MailtrapClient } from "mailtrap"; | ||
|
|
||
| const client = new MailtrapClient({ | ||
| token: process.env.MAILTRAP_API_KEY, | ||
| accountId: YOUR_ACCOUNT_ID | ||
| }); | ||
|
|
||
| async function getTrackingOptOuts() { | ||
| const response = await fetch( | ||
| "https://mailtrap.io/api/tracking_opt_outs", | ||
| { headers: { Authorization: `Bearer ${process.env.MAILTRAP_API_KEY}` } } | ||
| ); | ||
| const trackingOptOuts = await response.json(); | ||
| console.log("Tracking opt-outs:", trackingOptOuts); | ||
| } | ||
|
|
||
| getTrackingOptOuts(); | ||
| - lang: php | ||
| label: PHP | ||
| source: | | ||
| <?php | ||
| // Mailtrap SDK does not yet support tracking opt-outs. | ||
| // Use the cURL example above. | ||
| - lang: python | ||
| label: Python | ||
| source: | | ||
| # Mailtrap SDK does not yet support tracking opt-outs. | ||
| # Use the cURL example above. | ||
| - lang: ruby | ||
| label: Ruby | ||
| source: | | ||
| # Mailtrap SDK does not yet support tracking opt-outs. | ||
| # Use the cURL example above. | ||
| - lang: csharp | ||
| label: .NET | ||
| source: | | ||
| // Mailtrap SDK does not yet support tracking opt-outs. | ||
| // Use the cURL example above. | ||
| - lang: java | ||
| label: Java | ||
| source: | | ||
| // Mailtrap SDK does not yet support tracking opt-outs. | ||
| // Use the cURL example above. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Replace the Node.js fetch sample with an SDK-limitation note.
The JavaScript block is labeled as a Node.js x-codeSamples entry but does not use the Mailtrap SDK; it constructs a MailtrapClient and then falls back to raw fetch. That contradicts the stated “SDKs are deferred until support exists” approach and will mislead readers into assuming JS SDK support already exists.
Suggested change
- lang: javascript
label: Node.js
source: |
- import { MailtrapClient } from "mailtrap";
-
- const client = new MailtrapClient({
- token: process.env.MAILTRAP_API_KEY,
- accountId: YOUR_ACCOUNT_ID
- });
-
- async function getTrackingOptOuts() {
- const response = await fetch(
- "https://mailtrap.io/api/tracking_opt_outs",
- { headers: { Authorization: `Bearer ${process.env.MAILTRAP_API_KEY}` } }
- );
- const trackingOptOuts = await response.json();
- console.log("Tracking opt-outs:", trackingOptOuts);
- }
-
- getTrackingOptOuts();
+ // Mailtrap SDK does not yet support tracking opt-outs.
+ // Use the cURL example above.As per coding guidelines, "Use official Mailtrap SDKs for language-specific code examples in x-codeSamples; if SDK doesn't support a method, use GitBook generation or add a comment noting SDK limitations."
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - lang: javascript | |
| label: Node.js | |
| source: | | |
| import { MailtrapClient } from "mailtrap"; | |
| const client = new MailtrapClient({ | |
| token: process.env.MAILTRAP_API_KEY, | |
| accountId: YOUR_ACCOUNT_ID | |
| }); | |
| async function getTrackingOptOuts() { | |
| const response = await fetch( | |
| "https://mailtrap.io/api/tracking_opt_outs", | |
| { headers: { Authorization: `Bearer ${process.env.MAILTRAP_API_KEY}` } } | |
| ); | |
| const trackingOptOuts = await response.json(); | |
| console.log("Tracking opt-outs:", trackingOptOuts); | |
| } | |
| getTrackingOptOuts(); | |
| - lang: php | |
| label: PHP | |
| source: | | |
| <?php | |
| // Mailtrap SDK does not yet support tracking opt-outs. | |
| // Use the cURL example above. | |
| - lang: python | |
| label: Python | |
| source: | | |
| # Mailtrap SDK does not yet support tracking opt-outs. | |
| # Use the cURL example above. | |
| - lang: ruby | |
| label: Ruby | |
| source: | | |
| # Mailtrap SDK does not yet support tracking opt-outs. | |
| # Use the cURL example above. | |
| - lang: csharp | |
| label: .NET | |
| source: | | |
| // Mailtrap SDK does not yet support tracking opt-outs. | |
| // Use the cURL example above. | |
| - lang: java | |
| label: Java | |
| source: | | |
| // Mailtrap SDK does not yet support tracking opt-outs. | |
| // Use the cURL example above. | |
| - lang: javascript | |
| label: Node.js | |
| source: | | |
| // Mailtrap SDK does not yet support tracking opt-outs. | |
| // Use the cURL example above. | |
| - lang: php | |
| label: PHP | |
| source: | | |
| <?php | |
| // Mailtrap SDK does not yet support tracking opt-outs. | |
| // Use the cURL example above. | |
| - lang: python | |
| label: Python | |
| source: | | |
| # Mailtrap SDK does not yet support tracking opt-outs. | |
| # Use the cURL example above. | |
| - lang: ruby | |
| label: Ruby | |
| source: | | |
| # Mailtrap SDK does not yet support tracking opt-outs. | |
| # Use the cURL example above. | |
| - lang: csharp | |
| label: .NET | |
| source: | | |
| // Mailtrap SDK does not yet support tracking opt-outs. | |
| // Use the cURL example above. | |
| - lang: java | |
| label: Java | |
| source: | | |
| // Mailtrap SDK does not yet support tracking opt-outs. | |
| // Use the cURL example above. |
🤖 Prompt for 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.
In `@specs/email-sending.openapi.yml` around lines 1323 - 1368, The Node.js
x-codeSamples entry for tracking opt-outs mixes a MailtrapClient instantiation
with a raw fetch call, which is misleading because it implies SDK support that
does not exist. Update the JavaScript sample to match the other language blocks
by replacing the example in the tracking opt-outs section with an SDK-limitation
note, and remove the MailtrapClient/getTrackingOptOuts sample so readers are
directed to the cURL example until the SDK supports this endpoint.
Source: Coding guidelines
| x-codeSamples: | ||
| - lang: shell | ||
| label: 'cURL' | ||
| source: | | ||
| curl -X POST https://mailtrap.io/api/tracking_opt_outs \ | ||
| -H 'Authorization: Bearer YOUR_API_KEY' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "email": "tracked@example.com" | ||
| }' |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add the missing language sample slots for create/delete tracking opt-outs.
Line 1422 and Line 1469 only provide cURL. For spec files in this repo, x-codeSamples should still keep the standard language order, and unsupported SDK entries should be present with an explicit limitation note. Right now the POST/DELETE docs will lose the usual tabs and won’t communicate why the SDK samples are missing.
Based on learnings, populate x-codeSamples in the exact priority order with cURL first, then Node.js, PHP, Python, Ruby, .NET, and Java, using the same “SDK does not yet support tracking opt-outs” note you already added elsewhere.
Also applies to: 1469-1474
🧰 Tools
🪛 Betterleaks (1.5.0)
[high] 1426-1427: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
🤖 Prompt for 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.
In `@specs/email-sending.openapi.yml` around lines 1422 - 1431, The create/delete
tracking opt-outs docs only include cURL, so the standard code sample tabs are
missing for these operations. Update the x-codeSamples blocks in the
tracking_opt_outs POST/DELETE sections to follow the repo’s usual priority
order: cURL, Node.js, PHP, Python, Ruby, .NET, and Java, and include the same
explicit “SDK does not yet support tracking opt-outs” limitation note for the
unsupported SDK entries. Use the existing tracking opt-outs sample patterns in
this spec to keep the language ordering and messaging consistent.
Sources: Coding guidelines, Learnings
| const client = new MailtrapClient({ | ||
| token: process.env.MAILTRAP_API_KEY, | ||
| accountId: YOUR_ACCOUNT_ID | ||
| }); |
There was a problem hiding this comment.
This example do not use client, so if we want keep it - fetch is enough, but I think we should stick with curl only
There was a problem hiding this comment.
Yep, if an SDK doesn't support it yet we just don't give an example here, not even that "does not yet support" comment, leaving only cURL.
| - lang: php | ||
| label: PHP | ||
| source: | | ||
| <?php | ||
| // Mailtrap SDK does not yet support tracking opt-outs. | ||
| // Use the cURL example above. | ||
| - lang: python | ||
| label: Python | ||
| source: | | ||
| # Mailtrap SDK does not yet support tracking opt-outs. | ||
| # Use the cURL example above. | ||
| - lang: ruby | ||
| label: Ruby | ||
| source: | | ||
| # Mailtrap SDK does not yet support tracking opt-outs. | ||
| # Use the cURL example above. | ||
| - lang: csharp | ||
| label: .NET | ||
| source: | | ||
| // Mailtrap SDK does not yet support tracking opt-outs. | ||
| // Use the cURL example above. | ||
| - lang: java | ||
| label: Java | ||
| source: | | ||
| // Mailtrap SDK does not yet support tracking opt-outs. | ||
| // Use the cURL example above. |
There was a problem hiding this comment.
should we list those at all if we do not implement it? For other endpoints we just leave cURL (example: https://docs.mailtrap.io/developers/email-sending/email-logs)
3 participants
Motivation
https://railsware.atlassian.net/browse/MT-22654
Changes
tracking-opt-outstag and CRUD paths inemail-sending.openapi.yml(GET/POST/api/tracking_opt_outs,DELETE/api/tracking_opt_outs/{id})email,start_time,end_time,last_id), pagination limit, and rate limitsTrackingOptOutschema and response components matching Falcon v2 shapestracking_opt_out_enabledon sending domain GET/PATCHHow to test
Made with Cursor
Summary by CodeRabbit
New Features
Bug Fixes