Release v1.2.0 - Add Stats API

README.md

@@ -19,20 +19,20 @@ As a Maven dependency:
 <dependency>
     <groupId>io.mailtrap</groupId>
     <artifactId>mailtrap-java</artifactId>
-    <version>1.1.0</version>
+    <version>1.2.0</version>
 </dependency>
 ```
 
 As a Gradle Groovy dependency:
 
 ```groovy
-implementation 'io.mailtrap:mailtrap-java:1.1.0'
+implementation 'io.mailtrap:mailtrap-java:1.2.0'
 ```
 
 As a Gradle Kotlin DSL dependency:
 
 ```kotlin
-implementation("io.mailtrap:mailtrap-java:1.1.0")
+implementation("io.mailtrap:mailtrap-java:1.2.0")
 ```
 
 ## Usage

docs/getting-started.md

@@ -17,20 +17,20 @@ Maven dependency:
 <dependency>
     <groupId>io.mailtrap</groupId>
     <artifactId>mailtrap-java</artifactId>
-    <version>1.1.0</version>
+    <version>1.2.0</version>
 </dependency>
 ```
 
 Gradle Groovy dependency:
 
 ```groovy
-implementation 'io.mailtrap:mailtrap-java:1.1.0'
+implementation 'io.mailtrap:mailtrap-java:1.2.0'
 ```
 
 Gradle Kotlin DSL dependency:
 
 ```kotlin
-implementation("io.mailtrap:mailtrap-java:1.1.0")
+implementation("io.mailtrap:mailtrap-java:1.2.0")
 ```
 
 ### 2. Authentication

examples/java/io/mailtrap/examples/general/StatsExample.java

@@ -0,0 +1,39 @@
+package io.mailtrap.examples.general;
+
+import io.mailtrap.api.stats.StatsFilter;
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.factory.MailtrapClientFactory;
+
+public class StatsExample {
+
+    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
+    private static final long ACCOUNT_ID = 1L;
+
+    public static void main(String[] args) {
+        final var config = new MailtrapConfig.Builder()
+                .token(TOKEN)
+                .build();
+
+        final var client = MailtrapClientFactory.createMailtrapClient(config);
+
+        final var filter = StatsFilter.builder()
+                .startDate("2026-01-01")
+                .endDate("2026-01-31")
+                .build();
+
+        System.out.println("=== Aggregated Stats ===");
+        System.out.println(client.generalApi().stats().getStats(ACCOUNT_ID, filter));
+
+        System.out.println("\n=== Stats by Domains ===");
+        System.out.println(client.generalApi().stats().byDomains(ACCOUNT_ID, filter));
+
+        System.out.println("\n=== Stats by Categories ===");
+        System.out.println(client.generalApi().stats().byCategories(ACCOUNT_ID, filter));
+
+        System.out.println("\n=== Stats by Email Service Providers ===");
+        System.out.println(client.generalApi().stats().byEmailServiceProviders(ACCOUNT_ID, filter));
+
+        System.out.println("\n=== Stats by Date ===");
+        System.out.println(client.generalApi().stats().byDate(ACCOUNT_ID, filter));
+    }
+}

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>io.mailtrap</groupId>
     <artifactId>mailtrap-java</artifactId>
-    <version>1.1.0</version>
+    <version>1.2.0</version>
 
     <name>Mailtrap Java SDK</name>
     <description>The official Mailtrap SDK for Java provides Java APIs

src/main/java/io/mailtrap/api/stats/Stats.java

@@ -0,0 +1,57 @@
+package io.mailtrap.api.stats;
+
+import io.mailtrap.model.response.stats.SendingStatGroupResponse;
+import io.mailtrap.model.response.stats.SendingStatsResponse;
+
+import java.util.List;
+
+/**
+ * Interface representing the Mailtrap API for interaction with sending statistics
+ */
+public interface Stats {
+
+    /**
+     * Get aggregated sending stats
+     *
+     * @param accountId unique account ID
+     * @param filter    stats filter parameters
+     * @return aggregated sending statistics
+     */
+    SendingStatsResponse getStats(long accountId, StatsFilter filter);
+
+    /**
+     * Get sending stats grouped by domains
+     *
+     * @param accountId unique account ID
+     * @param filter    stats filter parameters
+     * @return list of sending statistics grouped by domain
+     */
+    List<SendingStatGroupResponse> byDomains(long accountId, StatsFilter filter);
+
+    /**
+     * Get sending stats grouped by categories
+     *
+     * @param accountId unique account ID
+     * @param filter    stats filter parameters
+     * @return list of sending statistics grouped by category
+     */
+    List<SendingStatGroupResponse> byCategories(long accountId, StatsFilter filter);
+
+    /**
+     * Get sending stats grouped by email service providers
+     *
+     * @param accountId unique account ID
+     * @param filter    stats filter parameters
+     * @return list of sending statistics grouped by email service provider
+     */
+    List<SendingStatGroupResponse> byEmailServiceProviders(long accountId, StatsFilter filter);
+
+    /**
+     * Get sending stats grouped by date
+     *
+     * @param accountId unique account ID
+     * @param filter    stats filter parameters
+     * @return list of sending statistics grouped by date
+     */
+    List<SendingStatGroupResponse> byDate(long accountId, StatsFilter filter);
+}

src/main/java/io/mailtrap/api/stats/StatsFilter.java

@@ -0,0 +1,21 @@
+package io.mailtrap.api.stats;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+@Builder
+public class StatsFilter {
+    private String startDate;
+    private String endDate;
+    private List<Long> sendingDomainIds;
+    private List<String> sendingStreams;
+    private List<String> categories;
+    private List<String> emailServiceProviders;
+}

src/main/java/io/mailtrap/api/stats/StatsImpl.java

@@ -0,0 +1,82 @@
+package io.mailtrap.api.stats;
+
+import io.mailtrap.Constants;
+import io.mailtrap.api.apiresource.ApiResource;
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.http.RequestData;
+import io.mailtrap.model.response.stats.SendingStatGroupResponse;
+import io.mailtrap.model.response.stats.SendingStatsResponse;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import static io.mailtrap.http.RequestData.entry;
+
+public class StatsImpl extends ApiResource implements Stats {
+
+    public StatsImpl(final MailtrapConfig config) {
+        super(config);
+        this.apiHost = Constants.GENERAL_HOST;
+    }
+
+    @Override
+    public SendingStatsResponse getStats(final long accountId, final StatsFilter filter) {
+        return httpClient.get(
+            buildUrl(accountId, ""),
+            new RequestData(buildStatsQueryParams(filter)),
+            SendingStatsResponse.class
+        );
+    }
+
+    @Override
+    public List<SendingStatGroupResponse> byDomains(final long accountId, final StatsFilter filter) {
+        return httpClient.getList(
+            buildUrl(accountId, "/domains"),
+            new RequestData(buildStatsQueryParams(filter)),
+            SendingStatGroupResponse.class
+        );
+    }
+
+    @Override
+    public List<SendingStatGroupResponse> byCategories(final long accountId, final StatsFilter filter) {
+        return httpClient.getList(
+            buildUrl(accountId, "/categories"),
+            new RequestData(buildStatsQueryParams(filter)),
+            SendingStatGroupResponse.class
+        );
+    }
+
+    @Override
+    public List<SendingStatGroupResponse> byEmailServiceProviders(final long accountId, final StatsFilter filter) {
+        return httpClient.getList(
+            buildUrl(accountId, "/email_service_providers"),
+            new RequestData(buildStatsQueryParams(filter)),
+            SendingStatGroupResponse.class
+        );
+    }
+
+    @Override
+    public List<SendingStatGroupResponse> byDate(final long accountId, final StatsFilter filter) {
+        return httpClient.getList(
+            buildUrl(accountId, "/date"),
+            new RequestData(buildStatsQueryParams(filter)),
+            SendingStatGroupResponse.class
+        );
+    }
+
+    private String buildUrl(final long accountId, final String suffix) {
+        return String.format(apiHost + "/api/accounts/%d/stats%s", accountId, suffix);
+    }
+
+    private Map<String, ? extends Optional<?>> buildStatsQueryParams(final StatsFilter filter) {
+        return RequestData.buildQueryParams(
+            entry("start_date", Optional.ofNullable(filter.getStartDate())),
+            entry("end_date", Optional.ofNullable(filter.getEndDate())),
+            entry("sending_domain_ids[]", Optional.ofNullable(filter.getSendingDomainIds())),
+            entry("sending_streams[]", Optional.ofNullable(filter.getSendingStreams())),
+            entry("categories[]", Optional.ofNullable(filter.getCategories())),
+            entry("email_service_providers[]", Optional.ofNullable(filter.getEmailServiceProviders()))
+        );
+    }
+}

src/main/java/io/mailtrap/client/api/MailtrapGeneralApi.java

@@ -4,6 +4,7 @@
 import io.mailtrap.api.accounts.Accounts;
 import io.mailtrap.api.billing.Billing;
 import io.mailtrap.api.permissions.Permissions;
+import io.mailtrap.api.stats.Stats;
 import lombok.Getter;
 import lombok.RequiredArgsConstructor;
 import lombok.experimental.Accessors;
@@ -19,4 +20,5 @@ public class MailtrapGeneralApi {
     private final Accounts accounts;
     private final Billing billing;
     private final Permissions permissions;
+    private final Stats stats;
 }

src/main/java/io/mailtrap/factory/MailtrapClientFactory.java

@@ -19,6 +19,7 @@
 import io.mailtrap.api.projects.ProjectsImpl;
 import io.mailtrap.api.sendingdomains.SendingDomainsImpl;
 import io.mailtrap.api.sendingemails.SendingEmailsImpl;
+import io.mailtrap.api.stats.StatsImpl;
 import io.mailtrap.api.suppressions.SuppressionsImpl;
 import io.mailtrap.api.testingemails.TestingEmailsImpl;
 import io.mailtrap.client.MailtrapClient;
@@ -87,8 +88,9 @@ private static MailtrapGeneralApi createGeneralApi(final MailtrapConfig config)
         final var accounts = new AccountsImpl(config);
         final var billing = new BillingImpl(config);
         final var permissions = new PermissionsImpl(config);
+        final var stats = new StatsImpl(config);
 
-        return new MailtrapGeneralApi(accountAccess, accounts, billing, permissions);
+        return new MailtrapGeneralApi(accountAccess, accounts, billing, permissions, stats);
     }
 
     private static MailtrapEmailSendingApi createSendingApi(final MailtrapConfig config) {

src/main/java/io/mailtrap/model/response/stats/SendingStatGroupResponse.java

@@ -0,0 +1,20 @@
+package io.mailtrap.model.response.stats;
+
+import com.fasterxml.jackson.annotation.JsonAnySetter;
+import lombok.Data;
+
+@Data
+public class SendingStatGroupResponse {
+
+    private String name;
+    private Object value;
+    private SendingStatsResponse stats;
+
+    @JsonAnySetter
+    public void setDynamicField(String key, Object value) {
+        if (!"stats".equals(key)) {
+            this.name = key;
+            this.value = value;
+        }
+    }
+}

src/main/java/io/mailtrap/model/response/stats/SendingStatsResponse.java

@@ -0,0 +1,38 @@
+package io.mailtrap.model.response.stats;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Data;
+
+@Data
+public class SendingStatsResponse {
+
+    @JsonProperty("delivery_count")
+    private int deliveryCount;
+
+    @JsonProperty("delivery_rate")
+    private double deliveryRate;
+
+    @JsonProperty("bounce_count")
+    private int bounceCount;
+
+    @JsonProperty("bounce_rate")
+    private double bounceRate;
+
+    @JsonProperty("open_count")
+    private int openCount;
+
+    @JsonProperty("open_rate")
+    private double openRate;
+
+    @JsonProperty("click_count")
+    private int clickCount;
+
+    @JsonProperty("click_rate")
+    private double clickRate;
+
+    @JsonProperty("spam_count")
+    private int spamCount;
+
+    @JsonProperty("spam_rate")
+    private double spamRate;
+}