Release v1.2.0 - Add Stats API

[piobeny]

Motivation

• Add support for the Email Sending Stats API (/api/accounts/{account_id}/stats) to the Java SDK, enabling users to retrieve aggregated email sending statistics.

Changes

• Add SendingStatsResponse model with delivery, bounce, open, click, and spam counts/rates (@JsonProperty annotated)
• Add SendingStatGroupResponse model with dynamic field deserialization via @JsonAnySetter
• Add StatsFilter builder class with startDate, endDate, and optional list filters (sendingDomainIds, sendingStreams, categories, emailServiceProviders)
• Add Stats interface with 5 methods: getStats, byDomains, byCategories, byEmailServiceProviders, byDate
• Add StatsImpl with query param serialization for array filters ([] suffix)
• Wire Stats into MailtrapGeneralApi
• Add unit tests with JSON fixtures
• Update README with Stats API reference

How to test

• stats.getStats(accountId, filter) with different filter parameters (startDate, endDate, sendingDomainIds, sendingStreams, categories, emailServiceProviders)
• Test grouped endpoints (byDomains, byCategories, byEmailServiceProviders, byDate) with filters

Examples

import io.mailtrap.MailtrapClient;
import io.mailtrap.api.stats.Stats;
import io.mailtrap.api.stats.StatsFilter;
import io.mailtrap.model.response.stats.SendingStatsResponse;
import io.mailtrap.model.response.stats.SendingStatGroupResponse;

MailtrapClient client = MailtrapClient.builder()
    .apiKey("api_key")
    .build();

Stats stats = client.general().stats();
long accountId = 12345;

// Get aggregated stats
StatsFilter filter = StatsFilter.builder()
    .startDate("2026-01-01")
    .endDate("2026-01-31")
    .build();
SendingStatsResponse result = stats.getStats(accountId, filter);

// Get stats with filters
StatsFilter filteredFilter = StatsFilter.builder()
    .startDate("2026-01-01")
    .endDate("2026-01-31")
    .sendingDomainIds(List.of(1L, 2L))
    .sendingStreams(List.of("transactional"))
    .categories(List.of("Welcome email"))
    .emailServiceProviders(List.of("Gmail"))
    .build();
SendingStatsResponse filtered = stats.getStats(accountId, filteredFilter);

// Get stats grouped by date
List<SendingStatGroupResponse> byDate = stats.byDate(accountId, filter);

// Get stats grouped by categories
List<SendingStatGroupResponse> byCategories = stats.byCategories(accountId, filter);

// Get stats grouped by email service providers
List<SendingStatGroupResponse> byEsp = stats.byEmailServiceProviders(accountId, filter);

// Get stats grouped by domains
List<SendingStatGroupResponse> byDomains = stats.byDomains(accountId, filter);

[coderabbitai]

Warning

Rate limit exceeded

@piobeny has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 12 minutes and 48 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.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 860d7d51-0d64-473f-ba33-6325b546e87e

📥 Commits

Reviewing files that changed from the base of the PR and between 1136e25 and fa5f2ac.

📒 Files selected for processing (17)

• README.md
• docs/getting-started.md
• examples/java/io/mailtrap/examples/general/StatsExample.java
• pom.xml
• src/main/java/io/mailtrap/api/stats/Stats.java
• src/main/java/io/mailtrap/api/stats/StatsFilter.java
• src/main/java/io/mailtrap/api/stats/StatsImpl.java
• src/main/java/io/mailtrap/client/api/MailtrapGeneralApi.java
• src/main/java/io/mailtrap/factory/MailtrapClientFactory.java
• src/main/java/io/mailtrap/model/response/stats/SendingStatGroupResponse.java
• src/main/java/io/mailtrap/model/response/stats/SendingStatsResponse.java
• src/test/java/io/mailtrap/api/stats/StatsImplTest.java
• src/test/resources/api/stats/byCategories.json
• src/test/resources/api/stats/byDate.json
• src/test/resources/api/stats/byDomains.json
• src/test/resources/api/stats/byEmailServiceProviders.json
• src/test/resources/api/stats/getStats.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch release-v1.2.0

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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