Add SDK code samples across API specs - #50
Conversation
Document all 19 inbound operations (folders, inboxes, messages, threads) with Node.js, PHP, Python, Ruby, .NET, and Java examples alongside the existing cURL, matching the x-codeSamples convention used across the other specs. Resource IDs use named variables (env vars for PHP) rather than inline literals.
Replace the remaining YOUR_API_TOKEN placeholders with YOUR_API_KEY across the specs so all code samples use one consistent placeholder.
Document API tokens (list/create/get/delete/reset) and sub-accounts (list/create) with Node.js, PHP, Python, Ruby, .NET, and Java examples, and add the missing Ruby example to the permissions operations. API-token samples use the account-scoped SDK methods the clients currently ship.
Add the Ruby example to the contact event/export operations and the two sandbox email-address operations, and add .NET and Java examples to the email-template get/update/delete operations, filling the per-language gaps where the SDK implements the endpoint.
Document email logs (list/get) and webhooks (create/list/get/update/delete) with Node.js, PHP, Python, Ruby, .NET, and Java examples, add the remaining five SDK examples to the account sending-stats operations, and add the Ruby example to the sending-domain update and company-info operations. Suppression create and tracking opt-outs have no SDK coverage and remain cURL-only.
|
Warning Review limit reached
Next review available in: 33 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe OpenAPI specifications standardize credential placeholders from ChangesAPI example updates
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
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: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
specs/contacts.openapi.yml (1)
69-203: 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick winUse environment variables in API-key placeholders.
The changed code samples still pass
YOUR_API_KEYdirectly to Mailtrap clients instead of reading the value from the environment. Use a placeholder backed byMAILTRAP_API_KEYin all cURL and SDK sample clients.🤖 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/contacts.openapi.yml` around lines 69 - 203, Replace every direct YOUR_API_KEY value in the cURL and SDK client samples with an environment-backed MAILTRAP_API_KEY placeholder, preserving each sample’s language-specific environment-variable syntax. Apply this throughout specs/contacts.openapi.yml at 69-203, 273-386, 426-432, 558-562, 651-718, 791-852, 925-973, 1034-1040, 1178-1182, 1285-1292, 1381-1387, 1482-1486, 1567-1573, 1671-1676, 1753-1757, 1850-1856, 1985-1989, 2074-2080, and 2200-2204; each listed site requires the same placeholder update.Source: Coding guidelines
🧹 Nitpick comments (4)
specs/email-sending.openapi.yml (2)
586-601: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winRead the API key from an environment variable in the new samples.
The new samples pass a literal
"YOUR_API_KEY"to the client constructor. Pre-existing samples in this same file read the key from the environment (process.env.MAILTRAP_API_KEY,$_ENV['MAILTRAP_API_KEY'],ENV['MAILTRAP_API_KEY']). The mixed style makes the documentation inconsistent within one page. Note that the PHP samples already follow the environment-variable style.
specs/email-sending.openapi.yml#L586-L601: change the Ruby sample toMailtrap::Client.new(api_key: ENV['MAILTRAP_API_KEY']); apply the same change to the Ruby samples at lines 810, 862, and 940.specs/email-sending.openapi.yml#L1524-L1558: change the Node.js sample totoken: process.env.MAILTRAP_API_KEYand the Python sample to read the token fromos.environ; apply the same change to the stats samples at lines 1635, 1659, 1756, 1780, 1870, 1894, 1984, and 2008, and to the C#/Java stats samples.specs/email-sending.openapi.yml#L2098-L2165: apply the same environment-variable change to the Node.js, Python, Ruby, C#, and Java email-log samples, including the get-by-id samples at lines 2212-2283.specs/email-sending.openapi.yml#L2326-L2454: apply the same environment-variable change to all webhook samples, including the list, get, update, and delete operations.As per coding guidelines: "Use environment variables for API keys in code samples (e.g., process.env.MAILTRAP_API_KEY)".
🤖 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 586 - 601, Replace literal API-key placeholders with the established MAILTRAP_API_KEY environment variable in every affected sample. In specs/email-sending.openapi.yml lines 586-601, 810, 862, and 940, update Ruby; lines 1524-1558, 1635, 1659, 1756, 1780, 1870, 1894, 1984, and 2008, update Node.js, Python, C#, and Java stats samples; lines 2098-2165 and 2212-2283, update all email-log language samples; and lines 2326-2454, update all webhook samples. Use each language’s existing environment-variable access convention, including Node.js process.env, Python os.environ, Ruby ENV, and the corresponding C#/Java environment APIs.Sources: Coding guidelines, Learnings
2154-2165: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueName or remove the null arguments in the Java email-logs sample.
The Java call now passes
accountId, null, null, which documents the first argument but leaves the second and third arguments opaque. If the SDK requires optional filters and pagination cursor, pass a named filter object or add a comment/nameless placeholder with named comments.🤖 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 2154 - 2165, The Java email-logs sample should clarify the two null arguments in the emailLogs().list call. Update the call to use the SDK’s named filter and pagination-cursor representation if available, or add concise inline comments identifying each null as the optional filter and pagination cursor while preserving the existing behavior.specs/inbound.openapi.yml (2)
697-700: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winShow the optional custom-domain request field.
The comments say to pass or set
domain_id, but every sample sends onlyname. Add a custom-domain variant with a named domain ID and the correct SDK property or builder method for each language. Otherwise, these samples demonstrate only Mailtrap-hosted inbox creation.Based on the PR objective, the create-inbox examples should explain how to pass optional
domain_idthrough the request.Also applies to: 714-716, 724-729, 738-741, 751-755, 766-770
🤖 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/inbound.openapi.yml` around lines 697 - 700, Update each create-inbox example around the visible inbox creation calls to include a custom-domain variant using a named domain ID and the SDK’s correct request property or builder method for that language. Keep the existing Mailtrap-hosted example, and ensure the samples explicitly demonstrate passing optional domain_id alongside the inbox name.
1164-1167: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winComplete the cursor-pagination examples.
The added samples fetch only the first page. Their comments mention
last_id, but none of the Node.js, PHP, Python, Ruby, .NET, or Java samples shows a second request using the returned cursor. Add that follow-up request for each SDK and verify the exact argument shape. The official Node.js example demonstrates a second request with{ last_id: page.last_id }. (github.com)Based on the PR objective, these examples should include usable
last_idpagination.Also applies to: 1180-1182, 1190-1193, 1202-1205, 1214-1216, 1226-1229, 1983-1986, 1999-2001, 2009-2012, 2021-2024, 2033-2035, 2045-2048
🤖 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/inbound.openapi.yml` around lines 1164 - 1167, Complete every cursor-pagination example for Node.js, PHP, Python, Ruby, .NET, and Java by adding a second `inbound.messages.getList` request that passes the first response’s `last_id` using the SDK’s verified argument shape. Update the samples near the existing `page`/`last_id` demonstrations, preserving each language’s conventions and ensuring the follow-up request is usable.Source: MCP tools
🤖 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/account-management.openapi.yml`:
- Around line 51-58: Replace every direct YOUR_API_KEY literal in the changed
examples with the appropriate language-specific environment-variable lookup; in
the Node.js MailtrapClient configuration, use process.env.MAILTRAP_API_KEY for
the token while preserving the existing sample structure.
- Around line 737-741: Update the Node.js API-token and organization sub-account
samples to configure accountId or organizationId on the MailtrapClient options,
then access the existing client.general or client.organizations namespaces as
objects. Replace callable namespace usage throughout the affected samples,
including client.general(accountId) and client.organizations(organizationId),
while preserving the demonstrated resource methods.
In `@specs/contacts.openapi.yml`:
- Around line 704-718: Replace the hard-coded Ruby account ID in the
ContactEventsAPI examples by using MAILTRAP_ACCOUNT_ID or a YOUR_ACCOUNT_ID
placeholder, while keeping the value as a Ruby integer at the call site; update
the anchor sample in specs/contacts.openapi.yml at 704-718 and the sibling
samples at 838-852 and 962-973 to follow the same pattern so no copied snippet
contains 1000001.
In `@specs/email-campaigns.openapi.yml`:
- Line 60: Replace literal API-key values in all changed samples with
environment-variable access: use ${MAILTRAP_API_KEY} for cURL in
specs/email-campaigns.openapi.yml at lines 60, 96, 135, 180, 217, 250, 290, 323,
354, 384, and 422; use process.env.MAILTRAP_API_KEY in
specs/sandbox-sending.openapi.yml at lines 54, 103, 122, and 173 and
specs/templates.openapi.yml at lines 149, 192, 206, 240, 317, 339, 352, 440,
468, 488, 568, 588, and 600; and use os.environ["MAILTRAP_API_KEY"] in the
Python samples at specs/sandbox.openapi.yml lines 244, 258, 292, 331, 362, 375,
410, 874, 917, 964, 1792, 1910, 2655, and 2690.
In `@specs/email-sending.openapi.yml`:
- Around line 805-815: Replace the Ruby sample’s CompanyInfoAPI construction and
get call with a supported direct API/HTTP request pattern, following the
existing curl or comparable SDK client examples; do not reference
CompanyInfoAPI#get, `#create`, or `#update`, and retain the domain lookup behavior.
---
Outside diff comments:
In `@specs/contacts.openapi.yml`:
- Around line 69-203: Replace every direct YOUR_API_KEY value in the cURL and
SDK client samples with an environment-backed MAILTRAP_API_KEY placeholder,
preserving each sample’s language-specific environment-variable syntax. Apply
this throughout specs/contacts.openapi.yml at 69-203, 273-386, 426-432, 558-562,
651-718, 791-852, 925-973, 1034-1040, 1178-1182, 1285-1292, 1381-1387,
1482-1486, 1567-1573, 1671-1676, 1753-1757, 1850-1856, 1985-1989, 2074-2080, and
2200-2204; each listed site requires the same placeholder update.
---
Nitpick comments:
In `@specs/email-sending.openapi.yml`:
- Around line 586-601: Replace literal API-key placeholders with the established
MAILTRAP_API_KEY environment variable in every affected sample. In
specs/email-sending.openapi.yml lines 586-601, 810, 862, and 940, update Ruby;
lines 1524-1558, 1635, 1659, 1756, 1780, 1870, 1894, 1984, and 2008, update
Node.js, Python, C#, and Java stats samples; lines 2098-2165 and 2212-2283,
update all email-log language samples; and lines 2326-2454, update all webhook
samples. Use each language’s existing environment-variable access convention,
including Node.js process.env, Python os.environ, Ruby ENV, and the
corresponding C#/Java environment APIs.
- Around line 2154-2165: The Java email-logs sample should clarify the two null
arguments in the emailLogs().list call. Update the call to use the SDK’s named
filter and pagination-cursor representation if available, or add concise inline
comments identifying each null as the optional filter and pagination cursor
while preserving the existing behavior.
In `@specs/inbound.openapi.yml`:
- Around line 697-700: Update each create-inbox example around the visible inbox
creation calls to include a custom-domain variant using a named domain ID and
the SDK’s correct request property or builder method for that language. Keep the
existing Mailtrap-hosted example, and ensure the samples explicitly demonstrate
passing optional domain_id alongside the inbox name.
- Around line 1164-1167: Complete every cursor-pagination example for Node.js,
PHP, Python, Ruby, .NET, and Java by adding a second `inbound.messages.getList`
request that passes the first response’s `last_id` using the SDK’s verified
argument shape. Update the samples near the existing `page`/`last_id`
demonstrations, preserving each language’s conventions and ensuring the
follow-up request is usable.
🪄 Autofix
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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 0990aa6e-f0dd-454d-b809-707150e26a8d
📒 Files selected for processing (8)
specs/account-management.openapi.ymlspecs/contacts.openapi.ymlspecs/email-campaigns.openapi.ymlspecs/email-sending.openapi.ymlspecs/inbound.openapi.ymlspecs/sandbox-sending.openapi.ymlspecs/sandbox.openapi.ymlspecs/templates.openapi.yml
The account-scoped resource accessors (general, organizations, stats, emailLogs, webhooks) are property getters that read accountId/organizationId from the client config, not functions. Pass the id via the MailtrapClient constructor and access the namespace as a property.
3 participants
Summary
Adds SDK code samples (
x-codeSamples) across the specs so the interactive docs show idiomatic usage for every endpoint our SDKs implement, and standardizes the API-key placeholder.Samples were written against the current SDK APIs (verified per client repo) and cover Node.js, PHP, Python, Ruby, .NET, and Java, in the established priority order (cURL first). ~3,200 lines across 7 specs.
What changed
YOUR_API_TOKENwithYOUR_API_KEYeverywhere so all samples use one placeholder.Resource IDs use named variables (env vars for PHP), matching the repo convention.
Intentionally left cURL-only
Verified no SDK implements these, so no SDK samples were added:
Notes for reviewers
/api/api_tokens(no account in path), but all SDKs currently call the account-scoped/api/accounts/{account_id}/api_tokens. Samples reflect current SDK behavior; they should be refreshed once the SDKs adopt the new token-scoped endpoint.Summary by CodeRabbit
YOUR_API_KEYplaceholder consistently.