Fix Python code examples in OpenAPI specifications to align with mailtrap-python SDK #10
Conversation
📝 WalkthroughWalkthroughReorganizes contact-related API into grouped sub-APIs, updates many Python method signatures to require account/identifier arguments and typed parameter wrappers, and modernizes sample IDs to string literals across contacts, email, general, and sandbox OpenAPI specs. Changes
Sequence Diagram(s)(Skipped — changes are API surface/signature and sample updates without a new multi-component runtime control flow that requires visualization.) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks✅ Passed checks (3 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 |
Ihor-Bilous
changed the title
Ihor-Bilous
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
specs/sandbox.openapi.yml (2)
803-818: Defineproject_idbefore using it in the create-inbox Python exampleIn the "Create an inbox" Python snippet,
project_idis used but never defined, so the example will raise aNameError.Proposed fix: add a `project_id` placeholder
client = mt.MailtrapClient( token="YOUR_API_TOKEN", - account_id="YOUR_ACCOUNT_ID" + account_id="YOUR_ACCOUNT_ID" ) - inbox = client.testing_api.inboxes.create( - project_id=project_id, - inbox_params=mt.InboxParams(name="My Test Inbox") - ) + project_id = 12345 + + inbox = client.testing_api.inboxes.create( + project_id=project_id, + inbox_params=mt.InboxParams(name="My Test Inbox") + )
2969-2986: Initializeinbox_idin the “Get messages” Python exampleIn the "Get messages" Python snippet,
inbox_idis passed toget_list(...)but never defined, so the sample will fail at runtime.Proposed fix: add an `inbox_id` placeholder
import mailtrap as mt client = mt.MailtrapClient( token="YOUR_API_TOKEN", - account_id="YOUR_ACCOUNT_ID" + account_id="YOUR_ACCOUNT_ID" ) - messages = client.testing_api.messages.get_list( - inbox_id=inbox_id - ) + inbox_id = 12345 + + messages = client.testing_api.messages.get_list( + inbox_id=inbox_id + )
🧹 Nitpick comments (1)
specs/email-api.openapi.yml (1)
1276-1293: Update/delete email template Python examples are consistentThe update and delete Python samples:
- Initialize
MailtrapClientwithtokenandaccount_idplaceholders.- Use
email_template_id = "TEMPLATE_ID"consistently across update and delete.- Call
update(...)anddelete(...)with structured params.
No syntax issues; only a minor style point that you could switch"TEMPLATE_ID"to something like"YOUR_TEMPLATE_ID"for consistency with other placeholders if you care.Also applies to: 1366-1374
📜 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
🧰 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/general.openapi.ymlspecs/contacts.openapi.ymlspecs/sandbox.openapi.ymlspecs/email-api.openapi.yml
🧠 Learnings (4)
📚 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/general.openapi.ymlspecs/contacts.openapi.ymlspecs/email-api.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/general.openapi.ymlspecs/contacts.openapi.ymlspecs/sandbox.openapi.ymlspecs/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 : Update contact URLs in spec `info` blocks to use `https://docs.mailtrap.io`, not help.mailtrap.io
Applied to files:
specs/contacts.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/sandbox.openapi.ymlspecs/email-api.openapi.yml
🔇 Additional comments (10)
specs/email-api.openapi.yml (4)
96-109: Python sending domain samples are now syntactically valid and consistentAll five Python snippets for sending domains (create, list, get, delete, send setup instructions) now:
- Use
account_id="YOUR_ACCOUNT_ID"instead of a bare identifier.- Follow a consistent
MailtrapClientinitialization pattern.
No further issues from a Python/Sphinx/doc-sample perspective.Also applies to: 200-243, 301-347, 403-447, 504-559
694-711: Suppressions Python examples look correct and alignedThe list/delete suppressions Python samples:
- Correctly initialize
MailtrapClientwithtokenandaccount_idplaceholders.- Use reasonable method calls on
suppressions_api.suppressions.
There are no syntax or obvious logic errors in these snippets.Also applies to: 849-862
960-1072: Email templates list/create Python samples are well-formedThe new/updated Python snippets for:
- Listing templates (
get_list()), and- Creating a template with
CreateEmailTemplateParams
are syntactically correct and consistent with other language samples (placeholders, account_id usage).
1197-1206: Get email template by ID: Python snippet looks goodThe added Python example for fetching an email template by ID uses:
- A concrete
template_id = 12345get_by_id(template_id)and printstemplate.name/template.id
This is a clear and runnable example as written.specs/sandbox.openapi.yml (2)
149-162: Project-related Python samples are now syntactically correct and consistentAcross create/list/get/update/delete project Python examples:
MailtrapClientis initialized with bothtokenandaccount_id="YOUR_ACCOUNT_ID".- IDs used in examples (
project_id = 12345, etc.) are defined before use.
These snippets should run as-is once real credentials/IDs are substituted.Also applies to: 271-284, 391-405, 501-517, 648-662
1888-1908: Sandbox send/batch Python samples are clear and consistentFor
/api/send/{inbox_id}and/api/batch/{inbox_id}:
- You now introduce an
inbox_idvariable and pass it intoMailtrapClient(sandbox=True, inbox_id=inbox_id).- The message/batch construction uses the expected
mt.Mail/mt.BatchSendEmailParamstypes.
These examples are syntactically valid and self-contained.Also applies to: 2099-2129
specs/general.openapi.yml (3)
209-220: Accounts Python example uses the updatedget_list()API correctlyThe Python snippet for
/api/accountsnow callsclient.general_api.accounts.get_list(), matching the naming used elsewhere (get_listinstead ofget_all). Initialization and loop logic are fine.
319-327: Account accesses Python examples are consistent and runnableFor listing and deleting account accesses:
- You define
account_id = "YOUR_ACCOUNT_ID"(andaccess_id = "ACCESS_ID"for delete).- You invoke
get_list(account_id)anddelete(account_id, access_id)onclient.general_api.account_accesses.
These samples are syntactically correct and consistent with the path structure.Also applies to: 423-431
792-797: Billing usage Python example looks correctThe billing Python snippet:
- Defines
account_id = "YOUR_ACCOUNT_ID".- Uses
client.general_api.billing.get_current_billing_usage(account_id)and prints a formatted summary.
This matches the described endpoint and is syntactically sound.specs/contacts.openapi.yml (1)
146-168: LGTM! Placeholder usage follows guidelines.The change to use string literal
"YOUR_ACCOUNT_ID"aligns with the coding guideline to use clear placeholders instead of actual environment variable references in documentation examples.Based on learnings, this prevents leaking secrets in documentation.
yanchuk
requested review from
VladimirTaytor,
andrii-porokhnavets and
yanchuk
There was a problem hiding this comment.
Actionable comments posted: 0
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)
892-892: Inconsistent example ID value.This example uses
inbox_id = 123456while other Python examples in this file useinbox_id = 12345(see lines 2104, 2978). For consistency across documentation, use the same example value.🔎 Suggested fix
-inbox_id = 123456 +inbox_id = 12345
🧹 Nitpick comments (1)
specs/sandbox.openapi.yml (1)
154-154: Standardize API token placeholder naming.Python examples inconsistently use both
"YOUR_API_TOKEN"and"YOUR_API_KEY"as placeholder names. For example:
- Lines 154, 276, 808: use
token="YOUR_API_TOKEN"- Lines 396, 506, 653 (and many others): use
token="YOUR_API_KEY"Standardize on one placeholder name throughout all Python examples. Based on common SDK documentation practices,
"YOUR_API_KEY"is recommended.Also applies to: 276-276, 808-808
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
specs/email-api.openapi.ymlspecs/sandbox.openapi.yml
🚧 Files skipped from review as they are similar to previous changes (1)
- specs/email-api.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/sandbox.openapi.yml
🧠 Learnings (3)
📓 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)
📚 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/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 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/sandbox.openapi.yml
🔇 Additional comments (1)
specs/sandbox.openapi.yml (1)
155-155: LGTM: Consistent use of string literal placeholders.The changes to use
account_id="YOUR_ACCOUNT_ID"as a string literal align with documentation best practices and the learning about using clear placeholders instead of environment variables to avoid leaking secrets.Based on learnings, this approach prevents accidental secret leakage in documentation while providing clear guidance to users.
Also applies to: 277-277, 397-397, 507-507, 654-654, 809-809
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
specs/email-api.openapi.yml (1)
960-966: Email Templates Python samples look coherent and cover full CRUDAcross all email template endpoints, the Python examples now:
- Initialize
MailtrapClientwith bothtokenandaccount_id.- Use a consistent
email_templates_api.templatesentrypoint.- Employ clearly named parameter types (
CreateEmailTemplateParams,UpdateEmailTemplateParams) and intuitive methods (get_list,create,get_by_id,update,delete).This makes the Python section align well with the other SDK examples and the described API behavior.
Two small nits you may optionally address:
- Placeholders alternate between
YOUR_API_KEYandYOUR_API_TOKENwithin this group; consider standardizing for consistency with the rest of the spec.- For update/delete, you use
"YOUR_TEMPLATE_ID"(string) while other places use numeric examples like12345; either is valid as a placeholder but a single style might be clearer.Please confirm the exact class and method names (
email_templates_api.templates.*,CreateEmailTemplateParams,UpdateEmailTemplateParams, and the keyword namestemplate_id,template_params) against the current mailtrap Python SDK before merging, as these are tightly coupled to the library’s API.Also applies to: 1059-1071, 1197-1206, 1276-1293, 1366-1376
📜 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
🧰 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/sandbox.openapi.ymlspecs/contacts.openapi.ymlspecs/general.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 : 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
📚 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/email-api.openapi.ymlspecs/sandbox.openapi.ymlspecs/contacts.openapi.ymlspecs/general.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 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/sandbox.openapi.ymlspecs/contacts.openapi.ymlspecs/general.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/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/contacts.openapi.yml
🔇 Additional comments (26)
specs/email-api.openapi.yml (2)
96-109: Python sending domains examples now correctly initializeMailtrapClientwithaccount_idThe five Python snippets for creating, listing, fetching, deleting sending domains and sending setup instructions all:
- Use
import mailtrap as mtandmt.MailtrapClient(...)withtoken="YOUR_API_KEY"andaccount_id="YOUR_ACCOUNT_ID".- Call the feature-specific APIs (
sending_domains_api.sending_domains.*) in a way that’s consistent with the resource names and other languages.This brings the examples in line with the official SDK and the other language samples in these sections.
Please cross-check the exact method and parameter names (
CreateSendingDomainParams,sending_domains_api.sending_domains.create/get_list/get_by_id/delete/send_setup_instructions) against the currently releasedmailtrapPython SDK to ensure there were no recent breaking changes before publishing the docs.Also applies to: 232-243, 333-347, 433-447, 543-559
694-711: Suppressions Python example is consistent with the SDK shape and account usageThe suppressions
GET /api/accounts/{account_id}/suppressionsPython sample:
- Correctly initializes
MailtrapClientwithaccount_id="YOUR_ACCOUNT_ID".- Uses
client.suppressions_api.suppressions.get_list()in a way that matches the intended “list + optional email filter” behavior described by the endpoint.Because this relies on the Python SDK surface (
suppressions_api.suppressions.get_listwith/without an argument), please verify against the latest SDK docs or a quick REPL check that the function signature still supports an optional email parameter in this form.specs/sandbox.openapi.yml (3)
149-162: Projects & Inboxes Python examples now correctly includeaccount_idand use testing APIsFor creating/listing/getting/updating/deleting projects and creating inboxes, the Python snippets:
- Initialize
MailtrapClientwithtoken="YOUR_API_TOKEN"(or"YOUR_API_KEY") andaccount_id="YOUR_ACCOUNT_ID".- Use the
testing_api.projectsandtesting_api.inboxesentrypoints with appropriate param objects (ProjectParams,InboxParams) and clear variable names (project_id,inbox_id).- Mirror the intent of the other language samples (PHP, Ruby, .NET, Java) while keeping a Pythonic style.
This matches the intended multi-language pattern and should be much more copy-pasteable for Python users.
Given these rely on the mailtrap Python SDK, please quickly validate that:
testing_api.projects.create/get_list/get_by_id/update/deleteaccept the shown positional/keyword arguments, andtesting_api.inboxes.create(project_id=..., inbox_params=...)matches the current function signature.
A short REPL or reference to the SDK’stesting/projects.pyandtesting/inboxes.pymodules should be enough.Also applies to: 273-286, 394-407, 504-520, 651-664, 806-821
1897-1915: Sandbox send & batch Python samples correctly passinbox_idthrough the SDKThe two Python examples for:
POST /api/send/{inbox_id}andPOST /api/batch/{inbox_id}now:
- Declare a local
inbox_id(e.g.,inbox_id = 123456/12345) and pass it intoMailtrapClient(sandbox=True, inbox_id=inbox_id) or via the client methods (batch_sendwithBatchSendEmailParams).- Use the
BatchSendEmailParams/BatchMail/BatchEmailRequesttypes in a way that lines up with how other languages construct equivalent payloads.This wiring should make sandbox sending via the Python SDK straightforward and explicit about which inbox receives the messages.
Please double-check the sandbox-specific Python SDK usage—
MailtrapClient(..., sandbox=True, inbox_id=...),BatchSendEmailParams,BatchMail, andBatchEmailRequest—against the latest mailtrap Python package to ensure these types and argument names haven’t shifted.Also applies to: 2116-2146
2992-3009: Inbox messages listing Python example is aligned with testing messages APIFor
GET /api/accounts/{account_id}/inboxes/{inbox_id}/messages, the Python snippet:
- Initializes
MailtrapClientwithtoken="YOUR_API_TOKEN"andaccount_id="YOUR_ACCOUNT_ID".- Uses
client.testing_api.messages.get_list(inbox_id=inbox_id)after defininginbox_id = 12345.- Iterates over messages and prints fields (
from_email,subject,created_at) consistent with the schema example.This matches the structure and intent of the other language samples and the documented response shape.
Because this depends on
testing_api.messages.get_listin the SDK, please confirm that the current method name and keyword (inbox_id) are still accurate in the latestmailtrapPython client before releasing the docs.specs/contacts.openapi.yml (16)
148-168: LGTM: Placeholder standardization applied correctly.The change from a numeric value to the string literal
"YOUR_ACCOUNT_ID"properly aligns with the coding guidelines to use clear placeholders in documentation examples.
346-362: LGTM: Consistent placeholder usage.The
account_idplaceholder and method signature align with the SDK conventions.
927-932: LGTM: Clean retrieval pattern.The
get_by_idmethod usage is consistent with SDK conventions, and the local variable assignment improves readability.
1158-1163: LGTM: Consistent retrieval pattern.The import status retrieval follows the same pattern as export retrieval, using
get_by_id.
1254-1257: LGTM: Method renamed to SDK convention.The change from
get_all()toget_list()aligns with the SDK's naming conventions.
1432-1435: LGTM: Consistent retrieval pattern.The list retrieval follows the established
get_by_idpattern.
1606-1610: LGTM: Clean delete pattern.The delete method follows a straightforward single-argument pattern.
1685-1688: LGTM: Method renamed to SDK convention.The change from
get_all()toget_list()maintains consistency across the SDK.
1906-1910: LGTM: Consistent retrieval pattern.The field retrieval follows the established
get_by_idpattern.
1988-1994: LGTM: Consistent update pattern with separate wrapper.The update method correctly uses
UpdateContactFieldParams(distinct fromCreateContactFieldParams), maintaining consistency with the update pattern used for contact lists.
2106-2109: LGTM: Clean delete pattern.The delete method follows the standard single-argument pattern.
1776-1780: Both wrapper class usages are correct. The create operation correctly usesmt.CreateContactFieldParamsand the update operation correctly usesmt.UpdateContactFieldParams. The distinction between the two wrappers is intentional—the create wrapper includes thedata_typeparameter while the update wrapper does not, which is appropriate for their respective operations.
1039-1046: The code sample is correct. The class nameImportContactParamsand parameterlist_ids_includedare accurate. The naming difference fromcreateContact(which useslist_ids) is intentional: batch import operations support both inclusion and exclusion lists, requiring separatelist_ids_includedandlist_ids_excludedparameters, while single contact creation uses a simplerlist_idsparameter.
1510-1518: Contact list update signature is correct.The Python code sample correctly uses the two-argument pattern:
client.contacts_api.contact_lists.update(list_id, mt.ContactListParams(name="Former Customers")). This signature is consistent across all SDK examples and matches the documented request body schema (object with name property).
705-714: Verify the contact events method signature and parameter wrapper in the mailtrap-python SDK.The Python example uses:
client.contacts_api.contact_events.create( contact_identifier="contact_id", contact_event_params=mt.ContactEventParams(...) )Ensure that:
- The wrapper class is named
ContactEventParams(notCreateContactEventParams)- The parameter name is
contact_event_params(not justparamsorevent_params)- The
contact_identifieris a required positional or keyword argument- The method path
client.contacts_api.contact_events.create()matches the current SDK implementationThe mailtrap-python SDK (v2.4.0, Dec 2025) needs manual verification against the actual package implementation to confirm this code sample is accurate.
1340-1342: Remove or correct the non-existentContactListParamsclass in the Python code example.The
mt.ContactListParamsclass does not exist in the official mailtrap-python SDK. The code example at lines 1340-1342 will fail at runtime. The mailtrap-python SDK uses module functions undercontacts/contact_lists.pyrather than parameter wrapper classes. Verify the correct method signature from the official SDK and provide a working example.Likely an incorrect or invalid review comment.
specs/general.openapi.yml (5)
211-220: LGTM: Method renamed to SDK convention.The change from
get_all()toget_list()maintains consistency across the SDK's naming conventions.
321-328: LGTM: Account ID now properly required.The method signature correctly requires
account_id, aligning with the endpoint path/api/accounts/{account_id}/account_accesses.
426-432: LGTM: Delete method now requires both IDs.The updated signature
delete(account_id, access_id)correctly reflects the endpoint's path parameters.
683-689: LGTM: Past review issue resolved.The variable naming issue (undefined
access_id) has been correctly fixed, and the method now properly receivesaccount_id.
795-801: LGTM: Descriptive method name and correct signature.The method rename to
get_current_billing_usageis more explicit, and theaccount_idparameter is correctly required.
| import mailtrap as mt | ||
| client = mt.MailtrapClient(token="YOUR_API_KEY", account_id=YOUR_ACCOUNT_ID) | ||
| client.general_api.permissions.bulk_update(access_id, permissions=[ | ||
| {"resource_id": "3281", "resource_type": "account", "access_level": "viewer"} | ||
| ]) | ||
| access_id = "ACCESS_ID" | ||
| account_access_id = "ACCOUNT_ACCESS_ID" | ||
| client = mt.MailtrapClient(token="YOUR_API_KEY") | ||
| client.general_api.permissions.bulk_permissions_update( | ||
| access_id, | ||
| account_access_id, | ||
| permissions=[ | ||
| mt.PermissionResourceParams( | ||
| resource_id="3281", resource_type="account", access_level="viewer" | ||
| ) | ||
| ] | ||
| ) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Search for bulk_permissions_update method definition
rg -A 15 "def bulk_permissions_update" --type pyRepository: mailtrap/mailtrap-openapi
Length of output: 217
🏁 Script executed:
# Also search for documentation or type hints around this method
rg -B 5 -A 15 "bulk_permissions_update" --type pyRepository: mailtrap/mailtrap-openapi
Length of output: 217
🏁 Script executed:
# Check if there are any test files or examples that show usage
fd -e py -type f | xargs rg "bulk_permissions_update" -B 2 -A 5Repository: mailtrap/mailtrap-openapi
Length of output: 826
🏁 Script executed:
# Search for the endpoint path in the spec
rg "bulk.*permissions" specs/general.openapi.yml -B 5 -A 10Repository: mailtrap/mailtrap-openapi
Length of output: 616
🏁 Script executed:
# Also check for the operationId that maps to bulk_permissions_update
rg "bulk_permissions_update" specs/general.openapi.yml -B 10 -A 5Repository: mailtrap/mailtrap-openapi
Length of output: 678
🏁 Script executed:
# Look for account access related endpoints to understand parameter order
rg "account_accesses" specs/general.openapi.yml -B 3 -A 3Repository: mailtrap/mailtrap-openapi
Length of output: 1459
🏁 Script executed:
# Get the full endpoint definition with parameters
rg -A 30 "'/api/accounts/\{account_id\}/account_accesses/\{account_access_id\}/permissions/bulk'" specs/general.openapi.ymlRepository: mailtrap/mailtrap-openapi
Length of output: 1564
🏁 Script executed:
# Check the parameters section for this endpoint
rg -B 5 "account_id.*path" specs/general.openapi.yml | head -50Repository: mailtrap/mailtrap-openapi
Length of output: 51
🏁 Script executed:
# Get full endpoint definition including parameter descriptions
rg -A 50 "'/api/accounts/\{account_id\}/account_accesses/\{account_access_id\}/permissions/bulk'" specs/general.openapi.yml | head -80Repository: mailtrap/mailtrap-openapi
Length of output: 2658
🏁 Script executed:
# Check how parameters are defined for this endpoint
rg -A 100 "operationId: updateUserPermissions" specs/general.openapi.yml | grep -A 30 "parameters:"Repository: mailtrap/mailtrap-openapi
Length of output: 51
🏁 Script executed:
# Look for the parameters section that follows the operationId
sed -n '/operationId: updateUserPermissions/,/parameters:/p' specs/general.openapi.yml | tail -30Repository: mailtrap/mailtrap-openapi
Length of output: 1140
🏁 Script executed:
# Extract the full endpoint definition more carefully
awk '/\/api\/accounts\/\{account_id\}\/account_accesses\/\{account_access_id\}\/permissions\/bulk/,/^ [^[:space:]]/ {print}' specs/general.openapi.yml | head -150Repository: mailtrap/mailtrap-openapi
Length of output: 154
🏁 Script executed:
# Find the parameters section for this endpoint
rg -A 20 "'/api/accounts/\{account_id\}/account_accesses/\{account_access_id\}/permissions/bulk'" specs/general.openapi.yml | tail -100Repository: mailtrap/mailtrap-openapi
Length of output: 1125
🏁 Script executed:
# Look at the broader context - parameters might be after responses
awk '/\/api\/accounts\/\{account_id\}\/account_accesses\/\{account_access_id\}\/permissions\/bulk/,/^ [\/x-]/ {print NR": "$0}' specs/general.openapi.yml | tail -50Repository: mailtrap/mailtrap-openapi
Length of output: 1690
🏁 Script executed:
# Find the account_access_id parameter definition
rg "account_access_id:" specs/general.openapi.yml -A 6Repository: mailtrap/mailtrap-openapi
Length of output: 51
🏁 Script executed:
# Get the complete parameters for the bulk permissions endpoint by looking at line context
sed -n '550,650p' specs/general.openapi.ymlRepository: mailtrap/mailtrap-openapi
Length of output: 3946
🏁 Script executed:
# Get the line numbers of the Python sample in the spec
rg -n "import mailtrap as mt" specs/general.openapi.ymlRepository: mailtrap/mailtrap-openapi
Length of output: 296
🏁 Script executed:
# Check what comes before the Python sample to see variable definitions
sed -n '520,540p' specs/general.openapi.ymlRepository: mailtrap/mailtrap-openapi
Length of output: 1002
🏁 Script executed:
# Get full context around line 534 with more lines
sed -n '500,550p' specs/general.openapi.ymlRepository: mailtrap/mailtrap-openapi
Length of output: 2308
Fix variable naming in Python code sample to match endpoint parameters.
The first parameter should be account_id, not access_id. The endpoint requires /api/accounts/{account_id}/account_accesses/{account_access_id}/permissions/bulk, so the code should define:
account_id = "YOUR_ACCOUNT_ID"
account_access_id = "ACCOUNT_ACCESS_ID"
client = mt.MailtrapClient(token="YOUR_API_KEY")
client.general_api.permissions.bulk_permissions_update(
account_id,
account_access_id,
permissions=[
mt.PermissionResourceParams(
resource_id="3281", resource_type="account", access_level="viewer"
)
]
)🤖 Prompt for AI Agents
In specs/general.openapi.yml around lines 534 to 548, the Python sample uses the
wrong variable name `access_id` for the first parameter; rename it to
`account_id` (and update its value to "YOUR_ACCOUNT_ID") and pass `account_id`
as the first argument to bulk_permissions_update, keeping the second variable
`account_access_id` as shown so the call matches the endpoint signature
/api/accounts/{account_id}/account_accesses/{account_access_id}/permissions/bulk.
2 participants
In this PR I fixed basic mistakes for python examples
This PR contain fixes of all Python code examples across OpenAPI files to match the lates mailtrap-dotnet SDK.
Motivation
Initial Python code examples in the OpenAPI (specs/*.openapi.yml) were inconsistent with the Python examples and guides from Mailtrap-Python SDK, what caused:
Incorrect client initialization
Wrong method signatures and APIs reference
Key Improvements:
Fixed client initialization
Enhanced constants naming: YOUR_ACCOUNT_ID applied to all examples
Corrected references of the APIs
Summary by CodeRabbit
New Features
Refactor
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.