Skip to content

Add support for Email Logs API#117

Open
mklocek wants to merge 1 commit intomainfrom
email-logs-api
Open

Add support for Email Logs API#117
mklocek wants to merge 1 commit intomainfrom
email-logs-api

Conversation

@mklocek
Copy link
Contributor

@mklocek mklocek commented Mar 10, 2026

Motivation

Add support for Email Logs API (https://docs.mailtrap.io/developers/email-sending/email-logs).

Summary by CodeRabbit

  • New Features

    • Added Email Logs API support: list and fetch message logs with filters, pagination and detailed event data.
    • Exposed emailLogs access on the client for easy usage.
  • Documentation

    • README updated with Email Logs examples and expanded Email Sandbox examples (batch, templates, message/inbox/project/attachment management).
    • CHANGELOG updated.
  • Tests

    • Added comprehensive unit tests covering Email Logs list/get and error scenarios.
  • Bug Fixes

    • Clarified accountId-missing error message for better guidance.

@coderabbitai
Copy link

coderabbitai bot commented Mar 10, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4fb67884-84d2-4fbb-b34b-168638358e00

📥 Commits

Reviewing files that changed from the base of the PR and between 910fefe and fc1a5d2.

📒 Files selected for processing (10)
  • CHANGELOG.md
  • README.md
  • examples/email-logs/everything.ts
  • src/__tests__/lib/api/resources/EmailLogs.test.ts
  • src/__tests__/lib/mailtrap-client.test.ts
  • src/config/index.ts
  • src/lib/MailtrapClient.ts
  • src/lib/api/EmailLogs.ts
  • src/lib/api/resources/EmailLogs.ts
  • src/types/api/email-logs.ts
🚧 Files skipped from review as they are similar to previous changes (5)
  • src/lib/MailtrapClient.ts
  • src/tests/lib/mailtrap-client.test.ts
  • src/lib/api/resources/EmailLogs.ts
  • src/config/index.ts
  • src/lib/api/EmailLogs.ts

📝 Walkthrough

Walkthrough

Adds a new Email Logs API to the Mailtrap Node.js client: types, API resource (list/get), a MailtrapClient getter, tests, example usage, and documentation/changelog updates. Includes deepObject query serialization for filters and pagination support.

Changes

Cohort / File(s) Summary
Changelog & README
CHANGELOG.md, README.md
Add Unreleased/4.x changelog entries and README examples for Email Logs and expanded sandbox examples.
Type Definitions
src/types/api/email-logs.ts
New, exported TypeScript models for email logs, message/event shapes, filter/operator types, pagination, and discriminated union event types.
API Resource Implementation
src/lib/api/resources/EmailLogs.ts
New EmailLogsApi with getList (serializes deepObject filters and search_after) and get methods; query serialization helper added.
API Wrapper
src/lib/api/EmailLogs.ts
New EmailLogsBaseAPI wrapper re-exposing bound getList and get methods for consumer-friendly usage.
Client Integration & Config
src/lib/MailtrapClient.ts, src/config/index.ts
Added emailLogs getter on MailtrapClient (validates accountId) and updated ERRORS.ACCOUNT_ID_MISSING message text.
Tests
src/__tests__/lib/api/resources/EmailLogs.test.ts, src/__tests__/lib/mailtrap-client.test.ts
Comprehensive unit tests for list/get flows, pagination, complex filters, array filters, and error mappings; MailtrapClient tests for the new getter and accountId validation.
Examples
examples/email-logs/everything.ts
New TypeScript example demonstrating client init, listing with filters/pagination, fetching a single message, and error handling.

Sequence Diagram(s)

sequenceDiagram
    participant Client as MailtrapClient
    participant Wrapper as EmailLogsBaseAPI
    participant Resource as EmailLogsApi
    participant Server as Mailtrap API

    Client->>Wrapper: client.emailLogs.getList(params)
    Wrapper->>Resource: bound getList(params)
    Resource->>Server: GET /accounts/{id}/email_logs?deepObject...
    Server-->>Resource: 200 OK (messages, next_page_cursor)
    Resource-->>Wrapper: parsed response
    Wrapper-->>Client: return EmailLogsList
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • Fix optional account #91 — Adds account-scoped API getters and validates/passes accountId; overlaps client getter patterns and account-scoped resource construction.
  • Restructure SDK #51 — Modifies MailtrapClient internals (getters/lazy creation) and touches similar client integration points.
  • Sending domains API #93 — Introduces other account-scoped API getters (e.g., sendingDomains) and tests; similar integration/testing patterns.

Suggested labels

feature request

Suggested reviewers

  • leonid-shevtsov
  • VladimirTaytor

Poem

🐰 I hop through logs with a curious twitch,
I chase every event, each bounce and stitch,
Filters and cursors guide where I roam,
Types keep my burrow organized at home,
Hooray — Email Logs have found their new niche! ✉️

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description provides only motivation but is missing the Changes and How to test sections required by the template, leaving the description incomplete. Add a detailed Changes section listing the key additions (new API class, types, tests, examples) and a How to test section with verification steps for the new Email Logs API functionality.
Docstring Coverage ⚠️ Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (1 passed)
Check name Status Explanation
Title check ✅ Passed The title directly and clearly describes the main change: adding support for the Email Logs API, which is reflected across all modified files.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
  • 📝 Generate docstrings (stacked PR)
  • 📝 Generate docstrings (commit on current branch)
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch email-logs-api

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.

@mklocek
Copy link
Contributor Author

mklocek commented Mar 10, 2026

@coderabbitai review

@coderabbitai
Copy link

coderabbitai bot commented Mar 10, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
examples/email-logs/everything.ts (1)

3-8: Consider using parseInt with validation for the placeholder.

Number("<YOUR-ACCOUNT-ID-HERE>") returns NaN. While this is just an example, users copying this code might not realize the issue immediately. Consider adding a comment or validation.

♻️ Suggested improvement
 const TOKEN = "<YOUR-TOKEN-HERE>";
-const ACCOUNT_ID = "<YOUR-ACCOUNT-ID-HERE>";
+const ACCOUNT_ID = "<YOUR-ACCOUNT-ID-HERE>"; // Replace with your numeric account ID

 const client = new MailtrapClient({
   token: TOKEN,
-  accountId: Number(ACCOUNT_ID),
+  accountId: parseInt(ACCOUNT_ID, 10), // Ensure this is a valid number
 });
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@examples/email-logs/everything.ts` around lines 3 - 8, The example currently
uses Number(ACCOUNT_ID) which yields NaN for the placeholder; update the
MailtrapClient instantiation to parse and validate the account ID (use
parseInt(ACCOUNT_ID, 10) or Number with a check), then handle invalid values
(throw a clear error or provide a helpful comment/instruction) before passing it
into new MailtrapClient so TOKEN, ACCOUNT_ID and the MailtrapClient(...) call
always receive a valid numeric accountId.
src/__tests__/lib/mailtrap-client.test.ts (1)

915-916: Consider using the ACCOUNT_ID_MISSING constant for consistency.

Other getter tests (e.g., lines 724, 761, 787) use new MailtrapError(ACCOUNT_ID_MISSING) for assertions, but this test uses a hardcoded string. Using the constant improves maintainability if the message changes again.

♻️ Suggested refactor
       expect(() => client.sendingDomains).toThrow(
-          "accountId is missing, please provide a valid accountId."
+          ACCOUNT_ID_MISSING
       );
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/__tests__/lib/mailtrap-client.test.ts` around lines 915 - 916, The test
for client.sendingDomains currently asserts a hardcoded error string; update it
to assert the canonical error object using the ACCOUNT_ID_MISSING constant
(i.e., replace the string-based toThrow assertion with toThrow(new
MailtrapError(ACCOUNT_ID_MISSING))) so it matches other getter tests that use
MailtrapError and ACCOUNT_ID_MISSING for consistency.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/__tests__/lib/api/resources/EmailLogs.test.ts`:
- Around line 71-81: The response interceptor added in the beforeAll (via
axios.interceptors.response.use with handleSendingError) is never removed;
capture the interceptor id when calling use() (e.g., store the return value from
axios.interceptors.response.use in a variable) and add an afterAll that ejects
it with axios.interceptors.response.eject(interceptorId); also ensure any
AxiosMockAdapter cleanup (mock.reset/restore) remains in afterEach/afterAll as
appropriate so the global axios instance is restored for other tests.

---

Nitpick comments:
In `@examples/email-logs/everything.ts`:
- Around line 3-8: The example currently uses Number(ACCOUNT_ID) which yields
NaN for the placeholder; update the MailtrapClient instantiation to parse and
validate the account ID (use parseInt(ACCOUNT_ID, 10) or Number with a check),
then handle invalid values (throw a clear error or provide a helpful
comment/instruction) before passing it into new MailtrapClient so TOKEN,
ACCOUNT_ID and the MailtrapClient(...) call always receive a valid numeric
accountId.

In `@src/__tests__/lib/mailtrap-client.test.ts`:
- Around line 915-916: The test for client.sendingDomains currently asserts a
hardcoded error string; update it to assert the canonical error object using the
ACCOUNT_ID_MISSING constant (i.e., replace the string-based toThrow assertion
with toThrow(new MailtrapError(ACCOUNT_ID_MISSING))) so it matches other getter
tests that use MailtrapError and ACCOUNT_ID_MISSING for consistency.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 12dc955b-e82f-4d66-af74-2e08dec5ef24

📥 Commits

Reviewing files that changed from the base of the PR and between 484d833 and 910fefe.

📒 Files selected for processing (10)
  • CHANGELOG.md
  • README.md
  • examples/email-logs/everything.ts
  • src/__tests__/lib/api/resources/EmailLogs.test.ts
  • src/__tests__/lib/mailtrap-client.test.ts
  • src/config/index.ts
  • src/lib/MailtrapClient.ts
  • src/lib/api/EmailLogs.ts
  • src/lib/api/resources/EmailLogs.ts
  • src/types/api/email-logs.ts

@mklocek mklocek marked this pull request as ready for review March 10, 2026 18:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant