Remove inexistent examples and update some Ruby SDK mistakes #8
Conversation
📝 WalkthroughWalkthroughOpenAPI specification files updated across four APIs to standardize Ruby code samples: replacing hard-coded account IDs (12345) with templated Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 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: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
specs/sandbox.openapi.yml (1)
1912-1922: Fix Ruby SDK client initialization — incorrect parameters and missing environment variables.The code sample contains multiple errors:
The
Mailtrap::Client.newmethod does not supportsandboxorinbox_idparameters. The SDK expects the inbox ID to be set via theMAILTRAP_TEST_INBOX_ID(orMAILTRAP_INBOX_ID) environment variable for sandbox sending.The API key must use an environment variable per coding guidelines. Update to
ENV['MAILTRAP_API_KEY']instead of the hardcoded'YOUR_API_TOKEN'.Replace
TEST_INBOX_IDwithENV['MAILTRAP_TEST_INBOX_ID']to follow SDK conventions.The corrected initialization should be:
client = Mailtrap::Client.new(api_key: ENV['MAILTRAP_API_KEY'])with
MAILTRAP_TEST_INBOX_IDenvironment variable set before the sample runs.
🧹 Nitpick comments (1)
specs/email-api.openapi.yml (1)
1228-1238: Good additions of Ruby samples for UPDATE and DELETE operations.These new Ruby code samples complete the CRUD operation coverage for email templates. The patterns are consistent with other samples. Note that these samples use
EMAIL_TEMPLATE_IDas a constant, which should match the convention established in other samples (some usetemplate_idas a variable).Consider standardizing the template ID reference across all samples for consistency - either use lowercase
template_idas a variable or uppercaseEMAIL_TEMPLATE_IDas a constant.Also applies to: 1311-1321
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
specs/contacts.openapi.ymlspecs/email-api.openapi.ymlspecs/general.openapi.ymlspecs/sandbox.openapi.yml
💤 Files with no reviewable changes (1)
- specs/general.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.ymlspecs/contacts.openapi.ymlspecs/sandbox.openapi.yml
🧠 Learnings (7)
📓 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 : Use official Mailtrap SDKs for language-specific code samples in `x-codeSamples`, with Node.js (mailtrap/mailtrap-nodejs), PHP (railsware/mailtrap-php), Python (railsware/mailtrap-python), and Ruby (railsware/mailtrap-ruby)
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 : Include code samples in `x-codeSamples` in this priority order: Node.js, PHP, Python, Ruby, .NET, Java, cURL
📚 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 Mailtrap SDKs for language-specific code samples in `x-codeSamples`, with Node.js (mailtrap/mailtrap-nodejs), PHP (railsware/mailtrap-php), Python (railsware/mailtrap-python), and Ruby (railsware/mailtrap-ruby)
Applied to files:
specs/email-api.openapi.ymlspecs/contacts.openapi.ymlspecs/sandbox.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 : Update contact URLs in spec `info` blocks to use `https://docs.mailtrap.io`, not help.mailtrap.io
Applied to files:
specs/email-api.openapi.ymlspecs/contacts.openapi.ymlspecs/sandbox.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 : Base URLs must never be changed in OpenAPI specs. Use `https://send.api.mailtrap.io` for transactional emails, `https://bulk.api.mailtrap.io` for bulk emails, and `https://mailtrap.io` for all other APIs
Applied to files:
specs/email-api.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/email-api.openapi.ymlspecs/sandbox.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 : Include code samples in `x-codeSamples` in this priority order: Node.js, PHP, Python, Ruby, .NET, Java, cURL
Applied to files:
specs/email-api.openapi.ymlspecs/sandbox.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 environment variables for API keys in code samples (e.g., `process.env.MAILTRAP_API_KEY`)
Applied to files:
specs/email-api.openapi.ymlspecs/sandbox.openapi.yml
🔇 Additional comments (9)
specs/email-api.openapi.yml (3)
1072-1084: Verify consistency with updated constructor pattern.The constructor now uses
YOUR_ACCOUNT_IDconsistently with other Ruby samples. Ensure this matches the verified Ruby SDK pattern once the earlier verification is complete.
1169-1179: Good addition of Ruby sample for GET template by ID.This new Ruby code sample improves SDK coverage. The pattern is consistent with other Ruby samples using
YOUR_ACCOUNT_IDand callingtemplates.get(template_id). Verify that thegetmethod name matches the official Ruby SDK.The verification can be done using the same script from the earlier comment to check if the
getmethod exists in the Ruby SDK.
967-973: No changes needed. The code sample is correct per the official mailtrap-ruby SDK:
EmailTemplatesAPI.newacceptsaccount_idas the first parameter ✓- The method name is
list(confirmed from SDK source:def list) ✓YOUR_ACCOUNT_IDis correctly used as a variable placeholder without quotes ✓specs/contacts.openapi.yml (5)
1221-1227: Verify ContactListsAPI method name change from get_all to list.Similar to the EmailTemplatesAPI changes, this Ruby sample changes the method name from
get_alltolist(line 1227). This suggests a consistent API naming convention across the Ruby SDK.Please verify that:
- The
listmethod name is correct for ContactListsAPI- This naming convention is consistent across all
*APIclasses in the Ruby SDK- The constructor pattern
ContactListsAPI.new(YOUR_ACCOUNT_ID, client)is correctThe verification script from the earlier comments can be extended to check ContactListsAPI as well.
Based on learnings, use official Mailtrap SDKs for code samples.
1636-1642: Consistent API pattern across ContactFieldsAPI.The ContactFieldsAPI follows the same pattern as other API classes:
- Constructor uses
YOUR_ACCOUNT_ID(line 1641)- Method renamed from
get_alltolist(line 1642)This consistency across
EmailTemplatesAPI,ContactListsAPI, andContactFieldsAPIsuggests a deliberate SDK-wide naming convention. The changes look correct and maintain consistency.Based on learnings, use official Mailtrap SDKs for code samples.
497-503: Verify ContactsAPI constructor pattern.The constructor now uses
YOUR_ACCOUNT_IDinstead of hard-coded12345across multiple ContactsAPI operations. Please verify this matches the official Ruby SDK (railsware/mailtrap-ruby) constructor signature:Mailtrap::ContactsAPI.new(YOUR_ACCOUNT_ID, client)#!/bin/bash # Verify ContactsAPI constructor and methods # Search for ContactsAPI class definition rg -n -A10 -B3 'class ContactsAPI' --type=rb # Check initialize method signature rg -n 'def initialize' --type=rb -A3 | rg -A3 'ContactsAPI'Based on learnings, use official Mailtrap SDKs for code samples.
Also applies to: 608-614
1017-1025: Method namecreateis correct for ContactImportsAPI in mailtrap-ruby SDK.The Ruby code sample correctly uses the
createmethod. The official mailtrap-ruby SDK atrailsware/mailtrap-rubyconfirms this is the correct method name and constructor signature:Mailtrap::ContactImportsAPI.new(account_id, client)followed byimports.create(...).
502-502: Remove or correct inaccurate method name change claims.The Ruby SDK uses
list(notget_all) andcreate(notcreate_import) as the official method names. The code samples in the spec already align with the official railsware/mailtrap-ruby SDK. Either these method names were never used before, or the original samples were already correct. The review comment incorrectly implies systematic changes from outdated method names to new ones. Verify the actual git diff to confirm what was actually changed before approving.specs/sandbox.openapi.yml (1)
290-298: Changes are consistent with the new API pattern.The
ProjectsAPIwrapper pattern andlistmethod are consistent with the createProject sample above. This approval is contingent on verifying the SDK API as noted in the previous comment.
| projects = Mailtrap::ProjectsAPI.new( | ||
| YOUR_ACCOUNT_ID, | ||
| client | ||
| ) | ||
| project = projects.create( | ||
| name: 'Example Project' | ||
| ) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's look at the actual file content around the changed lines
cat -n specs/sandbox.openapi.yml | sed -n '160,180p'Repository: mailtrap/mailtrap-openapi
Length of output: 712
🏁 Script executed:
# Also check the request body example mentioned (around line 107)
cat -n specs/sandbox.openapi.yml | sed -n '100,115p'Repository: mailtrap/mailtrap-openapi
Length of output: 676
🏁 Script executed:
# Check all the changed lines mentioned in the comment
cat -n specs/sandbox.openapi.yml | sed -n '285,305p'Repository: mailtrap/mailtrap-openapi
Length of output: 798
🏁 Script executed:
# Let's also check lines around 1912 and 1922
cat -n specs/sandbox.openapi.yml | sed -n '1905,1930p'Repository: mailtrap/mailtrap-openapi
Length of output: 1068
🌐 Web query:
mailtrap-ruby ProjectsAPI official SDK documentation
💡 Result:
Here are the official resources for the Mailtrap Ruby SDK and the Projects API documentation:
- Mailtrap Ruby SDK (official GitHub repo / README). [1]
- Mailtrap API v2 — Projects endpoints (Projects API reference). [2]
References:
[1] https://github.com/mailtrap/mailtrap-ruby
[2] https://api-docs.mailtrap.io/docs/mailtrap-api-docs/c088109b11d07-get-a-list-of-projects
🏁 Script executed:
# Let's check the official Ruby SDK repository structure and README
curl -s https://api.github.com/repos/railsware/mailtrap-ruby/contents/ | jq -r '.[] | select(.type=="file") | .name' | head -20Repository: mailtrap/mailtrap-openapi
Length of output: 133
🏁 Script executed:
# Get the README content to check the API documentation
curl -s https://raw.githubusercontent.com/railsware/mailtrap-ruby/main/README.md | head -200Repository: mailtrap/mailtrap-openapi
Length of output: 6106
🏁 Script executed:
# Let's also check the lib directory structure
curl -s https://api.github.com/repos/railsware/mailtrap-ruby/contents/lib | jq -r '.[] | .name'Repository: mailtrap/mailtrap-openapi
Length of output: 133
🏁 Script executed:
# Check the Ruby SDK source code to see what API classes are available
curl -s https://raw.githubusercontent.com/railsware/mailtrap-ruby/main/lib/mailtrap.rb | head -100Repository: mailtrap/mailtrap-openapi
Length of output: 900
🏁 Script executed:
# Look for the ProjectsAPI class definition
curl -s https://api.github.com/repos/railsware/mailtrap-ruby/git/trees/main?recursive=1 | grep -i projectRepository: mailtrap/mailtrap-openapi
Length of output: 51
🏁 Script executed:
# Try to get a list of all files in the lib directory
curl -s "https://api.github.com/repos/railsware/mailtrap-ruby/contents/lib?ref=main" 2>/dev/null | grep -o '"name":"[^"]*"' | head -30Repository: mailtrap/mailtrap-openapi
Length of output: 51
🌐 Web query:
mailtrap ruby SDK Projects API create list methods
💡 Result:
Short answer: use the Projects endpoints — GET /projects (list) and POST /projects (create). In Mailtrap’s Ruby SDK these map to the Projects API wrapper (methods named like list/get or create depending on version — e.g. a Projects (or ProjectsAPI) client that calls the API’s "get a list of projects" and "create project" endpoints). See Mailtrap API docs for endpoint details and the official Ruby client repo/docs for the SDK usage. [1][2][3]
Sources:
- Mailtrap API — Get a list of projects / Create project (API v2). [1]
- Official mailtrap-ruby GitHub repository (official Ruby client). [2]
- Mailtrap SDK / Ruby integration docs (overview of SDKs and features). [3]
References:
[1] https://api-docs.mailtrap.io/docs/mailtrap-api-docs/c088109b11d07-get-a-list-of-projects and https://api-docs.mailtrap.io/docs/mailtrap-api-docs/ee252e413d78a-create-project
[2] https://github.com/railsware/mailtrap-ruby
[3] https://help.mailtrap.io/article/140-mailtrap-ruby-integration
🏁 Script executed:
# Check if projects_api.rb exists in the Ruby SDK
curl -s "https://api.github.com/repos/railsware/mailtrap-ruby/contents/lib/mailtrap?ref=main" 2>/dev/null | grep -o '"name":"[^"]*"'Repository: mailtrap/mailtrap-openapi
Length of output: 51
🏁 Script executed:
# Get the email_templates_api.rb as a reference to understand the pattern
curl -s https://raw.githubusercontent.com/railsware/mailtrap-ruby/main/lib/mailtrap/email_templates_api.rbRepository: mailtrap/mailtrap-openapi
Length of output: 2419
🌐 Web query:
mailtrap-ruby "ProjectsAPI" class
💡 Result:
Do you want the ProjectsAPI class source code, its methods/usage examples, or help using it in your project?
🏁 Script executed:
# Search for any mention of ProjectsAPI in the official Ruby SDK repo
curl -s https://api.github.com/search/code?q=ProjectsAPI+repo:railsware/mailtrap-ruby | grep -o '"name":"[^"]*"' | head -20Repository: mailtrap/mailtrap-openapi
Length of output: 51
🏁 Script executed:
# Let's check if projects_api.rb file exists at all
curl -s https://raw.githubusercontent.com/railsware/mailtrap-ruby/main/lib/mailtrap/projects_api.rbRepository: mailtrap/mailtrap-openapi
Length of output: 83
🏁 Script executed:
# Let's look at the actual mailtrap.rb file content more thoroughly to see all requires
curl -s https://raw.githubusercontent.com/railsware/mailtrap-ruby/main/lib/mailtrap.rbRepository: mailtrap/mailtrap-openapi
Length of output: 900
🌐 Web query:
site:github.com/railsware/mailtrap-ruby ProjectsAPI
💡 Result:
I found the mailtrap/mailtrap-ruby repository on GitHub but there is no ProjectsAPI class/file in that repository. Source: mailtrap/mailtrap-ruby GitHub repo. [1]
[1] https://github.com/mailtrap/mailtrap-ruby
🏁 Script executed:
# Check the Client class to see what methods are available
curl -s https://raw.githubusercontent.com/railsware/mailtrap-ruby/main/lib/mailtrap/client.rb | head -100Repository: mailtrap/mailtrap-openapi
Length of output: 3728
🏁 Script executed:
# Let's check all files in the lib/mailtrap directory
curl -s "https://api.github.com/repos/railsware/mailtrap-ruby/contents/lib/mailtrap" 2>/dev/nullRepository: mailtrap/mailtrap-openapi
Length of output: 302
🌐 Web query:
mailtrap ruby SDK how to use projects API endpoints
💡 Result:
Do you want (A) a Ruby code example for calling Mailtrap Projects endpoints directly (HTTP), or (B) I should check whether the official mailtrap Ruby gem already implements the Projects (Email‑Sandbox) API and show how to use it?
🏁 Script executed:
# Let's verify the latest release/main branch version by checking gemspec or version
curl -s https://raw.githubusercontent.com/railsware/mailtrap-ruby/main/lib/mailtrap/version.rbRepository: mailtrap/mailtrap-openapi
Length of output: 139
🏁 Script executed:
# Check if there's any example showing how to use Projects API with the current SDK
curl -s https://raw.githubusercontent.com/railsware/mailtrap-ruby/main/examples/full.rb 2>/dev/nullRepository: mailtrap/mailtrap-openapi
Length of output: 2124
🌐 Web query:
mailtrap ruby SDK v2 how to access projects endpoint API key account management
💡 Result:
Short answer — use the mailtrap gem (API v2) Mailtrap::Client with an API token (Bearer auth). The gem exposes Testing (projects) endpoints via helper classes; API tokens / account-level permissions are created/managed in the Mailtrap UI (Settings → API Tokens).
Example (minimal):
- Install gem and create client:
client = Mailtrap::Client.new(api_key: ENV["MAILTRAP_API_KEY"]) # uses your API token. [1] - Call the Projects (Email Testing) API (the gem includes examples / Testing APIs — see examples in the repo). For the raw REST API the Projects endpoint is /api/projects (Mailtrap API v2). [1][3]
Where to find docs:
- mailtrap-ruby repo / usage & examples (shows Mailtrap::Client and examples). [1]
- Manage/create API tokens and set token permission (Account Admin vs project) in Mailtrap UI: Settings → API Tokens (use token as Bearer Authorization). [2]
- Mailtrap API v2 Projects endpoint docs (GET a list of projects / API reference). [3]
Sources:
[1] mailtrap/mailtrap-ruby (README, examples).
[2] Mailtrap — API Tokens (Settings → API Tokens; Bearer auth).
[3] Mailtrap API v2 — Get a list of projects (Projects endpoint).
🏁 Script executed:
# Final verification - let's check the most recent releases/tags to ensure we're checking the right version
curl -s "https://api.github.com/repos/railsware/mailtrap-ruby/releases?per_page=5" | grep -o '"tag_name":"[^"]*"'Repository: mailtrap/mailtrap-openapi
Length of output: 51
🏁 Script executed:
# Let's also verify what the Client class exposes as public methods
curl -s https://raw.githubusercontent.com/railsware/mailtrap-ruby/main/lib/mailtrap/client.rb | grep -E "^\s+def " | head -20Repository: mailtrap/mailtrap-openapi
Length of output: 779
The Mailtrap::ProjectsAPI class does not exist in the official mailtrap-ruby SDK (v2.5.0).
The updated Ruby samples at lines 169-176 and 290-293 will fail at runtime with a NameError. The mailtrap-ruby gem does not provide a ProjectsAPI wrapper for the Projects endpoints. While the REST API endpoints for projects exist (GET/POST /api/projects), the Ruby SDK does not include a corresponding domain class like it does for EmailTemplatesAPI or ContactsAPI.
Additionally, the sample uses 'Example Project' while the request body example (line 107) specifies 'My New Project'—update the sample to match the documented request body.
🤖 Prompt for AI Agents
In specs/sandbox.openapi.yml around lines 169-176 (and also update the parallel
sample at 290-293), replace the nonexistent Mailtrap::ProjectsAPI usage with a
call that uses the SDK's generic HTTP client to POST to /api/projects (e.g.,
invoke the client to send a POST request to the projects endpoint with a JSON
body). Also change the project name to match the request-body example ("My New
Project") and ensure request/response variable names reflect the raw client call
instead of a ProjectsAPI wrapper.
There were some mistakes in new documentation on Ruby SDK side of things, these changes aim to eliminate it.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.