[3.2.0] Add Email Templates API functionality #39
Conversation
WalkthroughThis update introduces a new "Get contact" API endpoint and comprehensive email template management via API, reflected in new classes, methods, and usage examples. Supporting tests and documentation are added or updated. Several example scripts now print HTTP status codes after delete operations instead of response bodies. Changes
Sequence Diagram(s)sequenceDiagram
participant ClientApp
participant MailtrapGeneralClient
participant EmailTemplateAPI
participant MailtrapAPI
ClientApp->>MailtrapGeneralClient: emailTemplates(accountId)
MailtrapGeneralClient->>EmailTemplateAPI: instantiate(accountId)
ClientApp->>EmailTemplateAPI: createEmailTemplate(dto)
EmailTemplateAPI->>MailtrapAPI: POST /accounts/{id}/email-templates
MailtrapAPI-->>EmailTemplateAPI: Response
EmailTemplateAPI-->>ClientApp: Response
ClientApp->>EmailTemplateAPI: getAllEmailTemplates()
EmailTemplateAPI->>MailtrapAPI: GET /accounts/{id}/email-templates
MailtrapAPI-->>EmailTemplateAPI: Response
EmailTemplateAPI-->>ClientApp: Response
ClientApp->>EmailTemplateAPI: updateEmailTemplate(templateId, dto)
EmailTemplateAPI->>MailtrapAPI: PATCH /accounts/{id}/email-templates/{templateId}
MailtrapAPI-->>EmailTemplateAPI: Response
EmailTemplateAPI-->>ClientApp: Response
ClientApp->>EmailTemplateAPI: deleteEmailTemplate(templateId)
EmailTemplateAPI->>MailtrapAPI: DELETE /accounts/{id}/email-templates/{templateId}
MailtrapAPI-->>EmailTemplateAPI: Response
EmailTemplateAPI-->>ClientApp: Response
sequenceDiagram
participant ClientApp
participant MailtrapGeneralClient
participant ContactAPI
participant MailtrapAPI
ClientApp->>MailtrapGeneralClient: contacts()
MailtrapGeneralClient->>ContactAPI: instantiate()
ClientApp->>ContactAPI: getContactById(contactId)
ContactAPI->>MailtrapAPI: GET /contacts/{contactId}
MailtrapAPI-->>ContactAPI: Response
ContactAPI-->>ClientApp: Response
ClientApp->>ContactAPI: getContactByEmail(email)
ContactAPI->>MailtrapAPI: GET /contacts/{email}
MailtrapAPI-->>ContactAPI: Response
ContactAPI-->>ClientApp: Response
Poem
✨ Finishing Touches
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
examples/general/contacts.php (1)
117-118: Consider adding context for the status code output.While printing the status code is more concise, consider adding a comment explaining what successful delete status codes to expect (e.g., 200, 204).
- // Print the response status code + // Print the response status code (200 or 204 indicates successful deletion) var_dump($response->getStatusCode());examples/general/emailTemplates.php (1)
1-109: Good example structure with comprehensive API coverage.The example script effectively demonstrates all email template operations with proper error handling. However, consider adding comments about replacing the hardcoded template IDs with actual values.
Consider adding a more prominent comment about the hardcoded template IDs:
- $templateId = 12345; // Replace with a valid template ID + $templateId = 12345; // IMPORTANT: Replace with an actual template ID from your account
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (15)
CHANGELOG.md(1 hunks)examples/general/contacts.php(2 hunks)examples/general/emailTemplates.php(1 hunks)examples/general/users.php(1 hunks)examples/testing/inboxes.php(1 hunks)examples/testing/messages.php(1 hunks)examples/testing/projects.php(1 hunks)src/Api/General/Contact.php(2 hunks)src/Api/General/EmailTemplate.php(1 hunks)src/DTO/Request/EmailTemplate.php(1 hunks)src/Exception/HttpClientException.php(1 hunks)src/MailtrapGeneralClient.php(2 hunks)tests/Api/General/ContactTest.php(1 hunks)tests/Api/General/EmailTemplateTest.php(1 hunks)tests/MailtrapGeneralClientTest.php(1 hunks)
🧰 Additional context used
🧬 Code Graph Analysis (2)
tests/MailtrapGeneralClientTest.php (1)
tests/MailtrapTestCase.php (1)
getConfigMock(38-57)
src/Api/General/Contact.php (1)
src/Api/AbstractApi.php (2)
handleResponse(84-111)httpGet(34-41)
🔇 Additional comments (16)
examples/testing/projects.php (1)
92-93: Good standardization of delete operation feedback.Changing from dumping the full response body to just the HTTP status code makes sense for delete operations, as the status code clearly indicates success or failure.
examples/testing/messages.php (1)
200-201: Consistent with delete operation standardization.This change aligns with the standardization effort across example scripts to output status codes for delete operations instead of full response bodies.
examples/testing/inboxes.php (1)
75-76: Consistent delete operation feedback pattern.Good consistency in applying the status code output pattern for delete operations across different resource examples.
examples/general/users.php (1)
42-43: Completes the delete operation standardization.This change completes the consistent pattern of outputting status codes for delete operations across all example scripts.
src/Api/General/Contact.php (2)
35-55: Well-designed contact retrieval methods.The new
getContactByIdandgetContactByEmailmethods follow the established pattern of delegating to a private method, maintaining consistency with existing update and delete operations in this class.
121-132: Proper implementation of contact retrieval logic.The private
getContactmethod correctly:
- Uses
urlencode()to safely handle special characters in IDs or emails- Follows the established pattern of using
handleResponse()for error handling- Constructs the URL path consistently with other methods in the class
CHANGELOG.md (1)
1-4: LGTM! Verify the release date.The changelog entry accurately documents the new features and follows the established format. However, please verify that the date "2025-06-12" is correct, as it appears to be in the future.
src/Exception/HttpClientException.php (1)
32-34: Excellent defensive programming practice.Adding a fallback error message when the response body is empty ensures consistent error reporting and improves debugging experience. This prevents scenarios where users would see empty error messages after API failures.
examples/general/contacts.php (1)
29-45: Good example demonstrating new contact retrieval functionality.The example clearly shows both ways to retrieve a contact (by ID and by email) with proper error handling. This will help users understand the new API endpoints.
src/MailtrapGeneralClient.php (2)
12-12: Perfect integration following established patterns.The method annotation correctly shows the EmailTemplate API requires an accountId parameter, consistent with other account-scoped APIs.
23-23: Consistent API mapping integration.The EmailTemplate class is properly added to the API_MAPPING, enabling the magic method functionality that users expect from the general client.
tests/MailtrapGeneralClientTest.php (1)
31-31: Proper test coverage for new EmailTemplate API mapping.The test correctly includes 'emailTemplates' in the match expression, ensuring it gets instantiated with the required accountId parameter like other account-scoped APIs.
tests/Api/General/ContactTest.php (1)
58-95: LGTM! Well-structured test methods with proper coverage.The new test methods
testGetContactByIdandtestGetContactByEmailfollow the established testing patterns and provide good coverage for the contact retrieval functionality. The URL encoding for email addresses is properly tested.tests/Api/General/EmailTemplateTest.php (1)
1-213: Excellent comprehensive test coverage.The test class provides thorough coverage of all email template operations including error scenarios. The mocking is properly implemented and assertions are comprehensive.
src/DTO/Request/EmailTemplate.php (1)
8-64: Clean and well-structured DTO implementation.The EmailTemplate DTO follows good practices with:
- Property promotion in constructor
- Static factory method for convenience
- Proper getter methods
- Correct snake_case conversion in
toArray()for API compatibilitysrc/Api/General/EmailTemplate.php (1)
15-97: Well-implemented API client following established patterns.The EmailTemplate API client is properly structured with:
- Correct inheritance and interface implementation
- Consistent URL path construction
- Appropriate HTTP methods for each operation
- Proper response handling through
handleResponse()The implementation follows the existing codebase patterns effectively.
gaalferov
requested review from
leonid-shevtsov,
IgorDobryn,
i7an,
mklocek and
VladimirTaytor
gaalferov
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
examples/general/contacts.php (3)
1-2: Addstrict_typesand fail-fast env-var checks at script startThe examples are a good reference, but omitting
declare(strict_types=1);and silent use ofgetenv()can lead to subtle type issues or mysterious 401s when the vars are unset.
Consider:<?php +declare(strict_types=1); + +$accountId = getenv('MAILTRAP_ACCOUNT_ID'); +$apiKey = getenv('MAILTRAP_API_KEY'); + +if (!$accountId || !$apiKey) { + fwrite(STDERR, "Please export MAILTRAP_ACCOUNT_ID and MAILTRAP_API_KEY\n"); + exit(1); +}This keeps the sample robust while remaining concise.
30-44: Avoid hard-coded IDs in examples; chain the create → read flowAll list-centric samples use
$contactListId = 1, which won’t exist in most accounts. New users will copy-paste and immediately receive 404s. Better UX:
- Create the list.
- Extract the returned ID.
- Use that ID for get / update / delete.
This keeps the snippet copy-pastable without edits.
88-90: Preferecho $response->getStatusCode(), PHP_EOLovervar_dumpfor scalars
var_dumpadds noise (int(204)). A plain echo is cleaner for scalar output and consistent with the preceding pretty-printed array dumps.tests/Api/General/ContactTest.php (2)
91-109: Use 201 status for “create” happy-path to mirror REST conventions
createContactListcurrently mocks a200. Mailtrap’s API (and the rest of the SDK) usually returns201 Createdfor resource creation—seecreateContacttest. Switching to201:- new Response(200, ['Content-Type' => 'application/json'], ...) + new Response(201, ['Content-Type' => 'application/json'], ...)keeps the expectations realistic and prevents accidental lax assertions.
138-144: Minor duplication: consider helper for base path compositionThe literal concatenation of
AbstractApi::DEFAULT_HOST . '/api/accounts/' . self::FAKE_ACCOUNT_IDis repeated ~20×.
A smallprivate function url(string $suffix): stringin the test class would reduce noise and future proof path changes.Not blocking, just readability.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
CHANGELOG.md(1 hunks)examples/general/contacts.php(2 hunks)src/Api/General/Contact.php(2 hunks)tests/Api/General/ContactTest.php(2 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- CHANGELOG.md
- src/Api/General/Contact.php
🧰 Additional context used
🧬 Code Graph Analysis (1)
examples/general/contacts.php (2)
src/Api/General/Contact.php (6)
getContactList(41-46)createContactList(54-62)updateContactList(71-79)deleteContactList(87-92)getContactById(100-103)getContactByEmail(111-114)src/Helper/ResponseHelper.php (1)
ResponseHelper(14-37)
Motivation
Support new functionality (Email templates)
https://help.mailtrap.io/article/105-email-templates
Changes
layerEmailTemplates intoMailtrapGeneralClientHow to test
composer testOR run PHP code from the example
Summary by CodeRabbit
New Features
Examples
Bug Fixes
Tests