Add Stats API

Author: piobeny

CHANGELOG.md

@@ -1,16 +1,24 @@
+## [2.5.0] - 2026-03-06
+
+- Add StatsApi with get, by_domains, by_categories, by_email_service_providers, by_date endpoints
+- Add api_query_params to RequestParams for automatic [] serialization of list query params
+
 ## [2.4.0] - 2025-12-04
-* Fix issue #52: Update README.md using new guideline by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/55
-* Fix issue #53: Add full usage in all examples by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/56
-* Merge functionality and examples in Readme by @yanchuk in https://github.com/mailtrap/mailtrap-python/pull/57
-* Fix issue #54: Add SendingDomainsApi, related models, tests, examples by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/58
+
+- Fix issue #52: Update README.md using new guideline by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/55
+- Fix issue #53: Add full usage in all examples by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/56
+- Merge functionality and examples in Readme by @yanchuk in https://github.com/mailtrap/mailtrap-python/pull/57
+- Fix issue #54: Add SendingDomainsApi, related models, tests, examples by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/58
 
 ## [2.3.0] - 2025-10-24
-* Fix issue #24: Add batch_send method to SendingApi, add models by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/47
-* Fix issue #42: Add GeneralApi, related models, examples, tests. by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/48
-* Fix issue #41: Add ContactExportsApi, related models, tests and examples by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/49
-* Fix issue #45: Add ContactEventsApi, related models, tests and examples by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/51
+
+- Fix issue #24: Add batch_send method to SendingApi, add models by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/47
+- Fix issue #42: Add GeneralApi, related models, examples, tests. by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/48
+- Fix issue #41: Add ContactExportsApi, related models, tests and examples by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/49
+- Fix issue #45: Add ContactEventsApi, related models, tests and examples by @Ihor-Bilous in https://github.com/mailtrap/mailtrap-python/pull/51
 
 ## [2.2.0] - 2025-09-18
+
 - Potential fix for code scanning alert no. 1: Workflow does not contain permissions by @mklocek in https://github.com/railsware/mailtrap-python/pull/15
 - Fix issue #29. Add support of Emails Sandbox (Testing) API: Projects by @Ihor-Bilous in https://github.com/railsware/mailtrap-python/pull/31
 - Issue 25 by @Ihor-Bilous in https://github.com/railsware/mailtrap-python/pull/33
@@ -25,13 +33,15 @@
 - Fix issue #28: Add AttachmentsApi, related models, tests, examples by @Ihor-Bilous in https://github.com/railsware/mailtrap-python/pull/44
 
 ## [2.1.0] - 2025-05-12
+
 - Add sandbox mode support in MailtrapClient
   - It requires inbox_id parameter to be set
 - Add bulk mode support in MailtrapClient
 - Drop support python 3.6 - 3.8
 - Add support for python 3.12 - 3.13
 
 ## [2.0.1] - 2023-05-18
+
 - Add User-Agent header to all requests
 
 ## [2.0.0] - 2023-03-11

examples/general/stats.py

@@ -1,10 +1,8 @@
 import mailtrap as mt
-from mailtrap.models.stats import SendingStatGroup
-from mailtrap.models.stats import SendingStats
-from mailtrap.models.stats import StatsFilterParams
+from mailtrap.models.stats import SendingStatGroup, SendingStats, StatsFilterParams
 
 API_TOKEN = "YOUR_API_TOKEN"
-ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+ACCOUNT_ID = 123456
 
 client = mt.MailtrapClient(token=API_TOKEN)
 stats_api = client.general_api.stats
@@ -41,7 +39,7 @@ def get_stats_with_filters(account_id: int) -> SendingStats:
         end_date="2026-01-31",
         sending_domain_ids=[1, 2],
         sending_streams=["transactional"],
-        categories=["Transactional", "Marketing"],
+        categories=["Welcome email", "Marketing"],
         email_service_providers=["Gmail", "Yahoo"],
     )
     return stats_api.get(account_id=account_id, params=params)
@@ -52,7 +50,7 @@ def get_stats_by_domains_with_filters(account_id: int) -> list[SendingStatGroup]
         start_date="2026-01-01",
         end_date="2026-01-31",
         sending_streams=["transactional"],
-        categories=["Transactional"],
+        categories=["Welcome email"],
     )
     return stats_api.by_domains(account_id=account_id, params=params)
 

mailtrap/api/resources/stats.py

@@ -1,9 +1,11 @@
+from typing import Literal
+
 from mailtrap.http import HttpClient
-from mailtrap.models.stats import SendingStatGroup
-from mailtrap.models.stats import SendingStats
-from mailtrap.models.stats import StatsFilterParams
+from mailtrap.models.stats import SendingStatGroup, SendingStats, StatsFilterParams
+
+GroupKey = Literal["domains", "categories", "email_service_providers", "date"]
 
-GROUP_KEYS = {
+_GROUP_KEYS = {
     "domains": "sending_domain_id",
     "categories": "category",
     "email_service_providers": "email_service_provider",
@@ -17,14 +19,21 @@ def __init__(self, client: HttpClient) -> None:
 
     def get(self, account_id: int, params: StatsFilterParams) -> SendingStats:
         """Get aggregated sending stats."""
-        response = self._client.get(self._base_path(account_id), params=params.api_query_params)
+        response = self._client.get(
+            self._base_path(account_id),
+            params=params.api_query_params,
+        )
         return SendingStats(**response)
 
-    def by_domains(self, account_id: int, params: StatsFilterParams) -> list[SendingStatGroup]:
+    def by_domains(
+        self, account_id: int, params: StatsFilterParams
+    ) -> list[SendingStatGroup]:
         """Get sending stats grouped by domains."""
         return self._grouped_stats(account_id, "domains", params)
 
-    def by_categories(self, account_id: int, params: StatsFilterParams) -> list[SendingStatGroup]:
+    def by_categories(
+        self, account_id: int, params: StatsFilterParams
+    ) -> list[SendingStatGroup]:
         """Get sending stats grouped by categories."""
         return self._grouped_stats(account_id, "categories", params)
 
@@ -34,17 +43,19 @@ def by_email_service_providers(
         """Get sending stats grouped by email service providers."""
         return self._grouped_stats(account_id, "email_service_providers", params)
 
-    def by_date(self, account_id: int, params: StatsFilterParams) -> list[SendingStatGroup]:
+    def by_date(
+        self, account_id: int, params: StatsFilterParams
+    ) -> list[SendingStatGroup]:
         """Get sending stats grouped by date."""
         return self._grouped_stats(account_id, "date", params)
 
     def _grouped_stats(
-        self, account_id: int, group: str, params: StatsFilterParams
+        self, account_id: int, group: GroupKey, params: StatsFilterParams
     ) -> list[SendingStatGroup]:
         response = self._client.get(
             f"{self._base_path(account_id)}/{group}", params=params.api_query_params
         )
-        group_key = GROUP_KEYS[group]
+        group_key = _GROUP_KEYS[group]
 
         return [
             SendingStatGroup(

mailtrap/models/stats.py

@@ -29,9 +29,9 @@ class SendingStatGroup:
 
 @dataclass
 class StatsFilterParams(RequestParams):
-    start_date: str = ""
-    end_date: str = ""
-    sending_domain_ids: Optional[list] = None
-    sending_streams: Optional[list] = None
-    categories: Optional[list] = None
-    email_service_providers: Optional[list] = None
+    start_date: Optional[str] = None
+    end_date: Optional[str] = None
+    sending_domain_ids: Optional[list[int]] = None
+    sending_streams: Optional[list[str]] = None
+    categories: Optional[list[str]] = None
+    email_service_providers: Optional[list[str]] = None

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mailtrap"
-version = "2.4.0"
+version = "2.5.0"
 description = "Official mailtrap.io API client"
 readme = "README.md"
 license = {file = "LICENSE.txt"}
@@ -23,7 +23,7 @@ dynamic = ["dependencies"]
 Homepage = "https://mailtrap.io/"
 Documentation = "https://github.com/railsware/mailtrap-python"
 Repository = "https://github.com/railsware/mailtrap-python.git"
-"API documentation" = "https://api-docs.mailtrap.io/"
+"API documentation" = "https://docs.mailtrap.io/developers"
 
 [build-system]
 requires = ["setuptools"]

tests/unit/api/general/test_stats.py

@@ -143,7 +143,9 @@ def test_get_should_return_sending_stats(
         assert stats.spam_rate == 0.013
 
     @responses.activate
-    def test_get_with_filter_params(self, client: StatsApi, sample_stats_dict: dict) -> None:
+    def test_get_with_filter_params(
+        self, client: StatsApi, sample_stats_dict: dict
+    ) -> None:
         responses.get(
             BASE_STATS_URL,
             json=sample_stats_dict,
@@ -155,16 +157,16 @@ def test_get_with_filter_params(self, client: StatsApi, sample_stats_dict: dict)
             end_date="2026-01-31",
             sending_domain_ids=[1, 2],
             sending_streams=["transactional"],
-            categories=["Transactional"],
+            categories=["Welcome email"],
             email_service_providers=["Gmail"],
         )
         client.get(ACCOUNT_ID, params)
 
         request_params = responses.calls[0].request.params
-        assert "sending_domain_ids[]" in request_params
-        assert "sending_streams[]" in request_params
-        assert "categories[]" in request_params
-        assert "email_service_providers[]" in request_params
+        assert request_params["sending_domain_ids[]"] == ["1", "2"]
+        assert request_params["sending_streams[]"] == "transactional"
+        assert request_params["categories[]"] == "Welcome email"
+        assert request_params["email_service_providers[]"] == "Gmail"
 
     @responses.activate
     def test_by_domains_should_return_grouped_stats(
@@ -192,7 +194,7 @@ def test_by_domains_should_return_grouped_stats(
     def test_by_categories_should_return_grouped_stats(self, client: StatsApi) -> None:
         response_data = [
             {
-                "category": "Transactional",
+                "category": "Welcome email",
                 "stats": {
                     "delivery_count": 100,
                     "delivery_rate": 0.97,
@@ -217,7 +219,7 @@ def test_by_categories_should_return_grouped_stats(self, client: StatsApi) -> No
 
         assert len(result) == 1
         assert result[0].name == "category"
-        assert result[0].value == "Transactional"
+        assert result[0].value == "Welcome email"
         assert result[0].stats.delivery_count == 100
 
     @responses.activate