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);