Updated imports and namings for Java SDK examples #6

vitalii-t · 2025-12-24T23:57:34Z

Summary by CodeRabbit

Refactor
- Reorganized Java client API method structures and naming conventions for contacts, email templates, bulk sending, and account management endpoints.
- Updated request and response type definitions for improved consistency.
- Restructured API method groupings to provide clearer resource organization and navigation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2025-12-24T23:57:43Z

Warning

Rate limit exceeded

@vitalii-t has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 12 minutes and 49 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 662c674 and b56453b.

📒 Files selected for processing (1)

specs/contacts.openapi.yml

📝 Walkthrough

Walkthrough

These changes update multiple OpenAPI specification files to refactor Java client API method signatures, reorganize API surface paths, introduce new request classes, and add account-scoped parameter patterns. Changes span email, contacts, and account management APIs.

Changes

Cohort / File(s)	Summary
Contacts API Refactoring `specs/contacts.openapi.yml`	Major API surface reorganization: renamed sub-APIs (contactExports, contactImports, contactLists, contactFields, contactEvents), updated method signatures to include accountId parameter, introduced new request classes (CreateUpdateContactListRequest, CreateContactFieldRequest, UpdateContactFieldRequest, CreateContactsExportRequest, CreateContactEventRequest, ImportContactsRequest), and adjusted operation names for clarity (e.g., getAll → findAll, create → createContactList).
Email Template API Updates `specs/email-api.openapi.yml`	Method rename: getAll → getAllTemplates; Request class refactored from CreateTemplateRequest to CreateEmailTemplateRequest wrapping EmailTemplate object; minor formatting adjustments.
Email Batch Model Types `specs/email-batch.openapi.yml`	Type renamings for batch operations: BatchMail → MailtrapBatchMail, BatchMail.Base → BatchEmailBase, BatchMail.Request → MailtrapMail; updated imports and builder invocations.
Bulk Email API `specs/email-sending-bulk.openapi.yml`	Client method renamed: bulkApi() → bulkSendingApi(); type imports relocated from io.mailtrap.model to io.mailtrap.model.request.emails for Address and MailtrapMail.
Transactional Email Sample `specs/email-sending-transactional.openapi.yml`	Code sample formatting: consolidated multi-line chained client creation to single-line MailtrapClientFactory.createMailtrapClient(config) invocation.
General/Account Management API `specs/general.openapi.yml`	Significant API surface changes: method renames (getAll → getAllAccounts, getUsage → getCurrentBillingCycleUsage), parameter reordering in account access methods (removeAccountAccess), new permission management flow (bulkUpdate → managePermissions with ManagePermissionsRequest, Permission, ResourceType, AccessLevel), and listUserAndInviteAccountAccesses replacing getAll with query parameters.
Testing/Sandbox API Patterns `specs/sandbox.openapi.yml`	Code sample pattern updates: consistent testingApi() wrapper introduction in client invocations, accountId parameter additions for account-scoped methods, and local ID variable extraction before API calls across projects, inboxes, messages, and attachments endpoints.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

.NET examples for Email section #1: Updates email template types and constructors (CreateTemplateRequest → CreateEmailTemplateRequest) with account-scoped client usage patterns in specs/email-api.openapi.yml.
Fix PHP code examples in OpenAPI specifications #3: Modifies specs/contacts.openapi.yml with identical API-surface changes including account-scoped methods, renamed DTOs, and reorganized sub-APIs for exports/imports/events.

Suggested reviewers

mklocek
VladimirTaytor
yanchuk

🐰 The API paths hop along,
With new signatures strong and true,
Account IDs now tag along,
Old method names bid adieu,
A cleaner warren shines through! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change across the pull request: updating Java SDK example code with new imports and API method namings.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

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 (3)

specs/contacts.openapi.yml (2)
1506-1515: Missing import statement for CreateUpdateContactListRequest.

The code uses CreateUpdateContactListRequest at line 1515, but the import statement is not included in this snippet. This will cause a compilation error.
🔎 Proposed fix
 import io.mailtrap.config.MailtrapConfig;
 import io.mailtrap.factory.MailtrapClientFactory;
+import io.mailtrap.model.request.contactlists.CreateUpdateContactListRequest;
 
 var config = new MailtrapConfig.Builder().token("YOUR_API_KEY").build();
934-942: Fix Java method name for consistency with other endpoints.

Line 942 uses client.contactsApi().exports().get(...) but should use contactExports() to match the pattern used elsewhere in the file (line 842: contactExports().createContactExport(...)). All other sub-API methods follow the naming convention contactsApi().<resourceType>() (e.g., contactEvents(), contactImports(), contactLists(), contactFields()).
specs/sandbox.openapi.yml (1)
3726-3736: Java HTML analysis example uses messageId without declaring it

In the Java sample for /messages/{message_id}/analyze, messageId is passed to getMessageHtmlAnalysis(accountId, inboxId, messageId) but is never declared in the snippet, unlike other nearby Java examples that define both inboxId and messageId.

Add a declaration, e.g.:
 long inboxId = 12345L;
+long messageId = 67890L;
 var htmlAnalysis = client.testingApi().messages()
-    .getMessageHtmlAnalysis(accountId, inboxId, messageId);
+    .getMessageHtmlAnalysis(accountId, inboxId, messageId);
so the example is self‑contained and consistent with the other message‑level snippets.

🧹 Nitpick comments (4)

specs/sandbox.openapi.yml (1)
190-210: Java sandbox samples now pass accountId but never show how it’s defined

All updated Java examples under client.testingApi().* now take accountId (and often projectId/inboxId/messageId) explicitly, which matches the REST paths, but none of these snippets declare accountId. That makes the samples non-compilable when copy‑pasted.

Consider adding a short declaration (or a comment) in each snippet, e.g.:
long accountId = 12345L; // your Mailtrap account ID
and similarly for projectId, inboxId, messageId, attachmentId where they are first introduced. This will align the Java samples with the more explicit PHP/Ruby examples and avoid confusion.

Please double‑check the Java client docs or signatures to ensure these parameter orders (accountId, inboxId, messageId, ...) match the latest SDK before updating all snippets.

Also applies to: 310-323, 429-445, 547-568, 686-702, 843-865, 972-988, 1369-1385, 1488-1504, 1607-1623, 1726-1742, 1955-1970, 2539-2557, 2779-2803, 2991-3009, 3215-3235, 3558-3570, 3838-3850, 3996-4008, 4129-4141, 4264-4275, 4422-4434, 4667-4679, 4795-4806
specs/email-api.openapi.yml (1)
1177-1189: Java create‑template example: add imports and tidy the new request construction

The switch to CreateEmailTemplateRequest + EmailTemplate matches the new Java client model, but the snippet:

Uses CreateEmailTemplateRequest and EmailTemplate without showing their imports.

Has formatting that makes the nested constructor harder to read.

Consider something like:
import io.mailtrap.config.MailtrapConfig;
import io.mailtrap.factory.MailtrapClientFactory;
import io.mailtrap.model.request.emails.EmailTemplate;
import io.mailtrap.model.request.emails.CreateEmailTemplateRequest;

var config = new MailtrapConfig.Builder()
    .token("YOUR_API_TOKEN")
    .build();
var client = MailtrapClientFactory.createMailtrapClient(config);

long accountId = 12345L; // your account ID

var request = new CreateEmailTemplateRequest(
    new EmailTemplate(
        "Welcome Email",
        "onboarding",
        "Welcome to {{company_name}}!",
        "Welcome {{user_name}}!",
        "<h1>Welcome {{user_name}}!</h1>"
    )
);

var template = client.emailTemplatesApi()
    .emailTemplates()
    .createEmailTemplate(accountId, request);
which is more copy‑pasteable for users.

Please verify the fully‑qualified class names and constructor parameter order for EmailTemplate and CreateEmailTemplateRequest against the Java SDK.
specs/general.openapi.yml (2)
173-180: Java general‑API samples: new method names look correct, but IDs are implicitly defined

Across these Java snippets you’ve:

Switched to MailtrapClientFactory.createMailtrapClient(config) and client.generalApi() usage.

Updated methods to getAllAccounts(), listUserAndInviteAccountAccesses(...), removeAccountAccess(...), getResources(accountId), and getCurrentBillingCycleUsage(accountId).

This aligns with the described Java SDK refactor. The only gap is that accountId / accessId are used but never introduced; a brief declaration per snippet (or a comment like long accountId = 12345L;) would make these examples self‑contained and easier to copy.

Please confirm the new method names and argument order (accountId vs accessId) with the Java SDK to avoid drift between docs and client code.

Also applies to: 272-280, 377-384, 634-641, 748-755

491-511: Java managePermissions example: missing List import and minor clarity improvement

The ManagePermissionsRequest + Permission usage is good, but:

List.of(...) is used without showing an import for java.util.List.

It may help to comment what false in the Permission constructor represents (e.g., _destroy flag).

You could make the snippet more explicit:
import java.util.List;
import io.mailtrap.model.AccessLevel;
import io.mailtrap.model.ResourceType;
import io.mailtrap.model.request.permissions.ManagePermissionsRequest;
import io.mailtrap.model.request.permissions.Permission;

long accountId = 12345L;
long accessId = 67890L;

var request = new ManagePermissionsRequest(
    List.of(
        new Permission(
            "3281",
            ResourceType.ACCOUNT,
            AccessLevel.VIEWER,
            false // do not destroy; create or update
        )
    )
);

client.generalApi()
    .permissions()
    .managePermissions(accessId, accountId, request);
so users can paste it directly into a Java project.

Please verify the constructor signature for Permission and the ordering of parameters in managePermissions against the Java client library.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 07f0cbe and 662c674.

📒 Files selected for processing (7)

specs/contacts.openapi.yml
specs/email-api.openapi.yml
specs/email-batch.openapi.yml
specs/email-sending-bulk.openapi.yml
specs/email-sending-transactional.openapi.yml
specs/general.openapi.yml
specs/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. 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
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 spec info blocks to use https://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 in x-codeSamples in this priority order: Node.js, PHP, Python, Ruby, .NET, Java, cURL
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)
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, and x-logo
Structure tags with x-page-title, x-page-description, and x-parent for 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-sending-transactional.openapi.yml
specs/email-api.openapi.yml
specs/email-batch.openapi.yml
specs/sandbox.openapi.yml
specs/contacts.openapi.yml
specs/general.openapi.yml
specs/email-sending-bulk.openapi.yml

🧠 Learnings (8)

📓 Common learnings

Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T11:20:58.562Z
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.562Z
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')