Add Stats API

Author: piobeny

CHANGELOG.md

@@ -1,16 +1,24 @@
+## [Unreleased]
+
+- Add StatsApi with get, by_domain, by_category, by_email_service_provider, 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

README.md

@@ -247,6 +247,9 @@ The same situation applies to both `client.batch_send()` and `client.sending_api
 ### Suppressions API:
 - Suppressions (find & delete) – [`suppressions/suppressions.py`](examples/suppressions/suppressions.py)
 
+### Stats API:
+- Sending stats – [`stats/stats.py`](examples/stats/stats.py)
+
 ### General API:
 - Account Accesses management – [`general/account_accesses.py`](examples/general/account_accesses.py)
 - Accounts info – [`general/accounts.py`](examples/general/accounts.py)

examples/stats/stats.py

@@ -0,0 +1,67 @@
+import mailtrap as mt
+from mailtrap.models.stats import SendingStatGroup
+from mailtrap.models.stats import SendingStats
+from mailtrap.models.stats import StatsFilterParams
+
+API_TOKEN = "YOUR_API_TOKEN"
+ACCOUNT_ID = "YOUR_ACCOUNT_ID"
+
+client = mt.MailtrapClient(token=API_TOKEN)
+stats_api = client.stats_api
+
+
+def get_stats(account_id: int) -> SendingStats:
+    params = StatsFilterParams(start_date="2026-01-01", end_date="2026-01-31")
+    return stats_api.get(account_id=account_id, params=params)
+
+
+def get_stats_by_domain(account_id: int) -> list[SendingStatGroup]:
+    params = StatsFilterParams(start_date="2026-01-01", end_date="2026-01-31")
+    return stats_api.by_domain(account_id=account_id, params=params)
+
+
+def get_stats_by_category(account_id: int) -> list[SendingStatGroup]:
+    params = StatsFilterParams(start_date="2026-01-01", end_date="2026-01-31")
+    return stats_api.by_category(account_id=account_id, params=params)
+
+
+def get_stats_by_email_service_provider(account_id: int) -> list[SendingStatGroup]:
+    params = StatsFilterParams(start_date="2026-01-01", end_date="2026-01-31")
+    return stats_api.by_email_service_provider(account_id=account_id, params=params)
+
+
+def get_stats_by_date(account_id: int) -> list[SendingStatGroup]:
+    params = StatsFilterParams(start_date="2026-01-01", end_date="2026-01-31")
+    return stats_api.by_date(account_id=account_id, params=params)
+
+
+def get_stats_with_filters(account_id: int) -> SendingStats:
+    params = StatsFilterParams(
+        start_date="2026-01-01",
+        end_date="2026-01-31",
+        sending_domain_ids=[1, 2],
+        sending_streams=["transactional"],
+        categories=["Welcome email", "Marketing"],
+        email_service_providers=["Gmail", "Yahoo"],
+    )
+    return stats_api.get(account_id=account_id, params=params)
+
+
+def get_stats_by_domain_with_filters(account_id: int) -> list[SendingStatGroup]:
+    params = StatsFilterParams(
+        start_date="2026-01-01",
+        end_date="2026-01-31",
+        sending_streams=["transactional"],
+        categories=["Welcome email"],
+    )
+    return stats_api.by_domain(account_id=account_id, params=params)
+
+
+if __name__ == "__main__":
+    print(get_stats(ACCOUNT_ID))
+    print(get_stats_by_domain(ACCOUNT_ID))
+    print(get_stats_by_category(ACCOUNT_ID))
+    print(get_stats_by_email_service_provider(ACCOUNT_ID))
+    print(get_stats_by_date(ACCOUNT_ID))
+    print(get_stats_with_filters(ACCOUNT_ID))
+    print(get_stats_by_domain_with_filters(ACCOUNT_ID))

mailtrap/__init__.py

@@ -32,5 +32,6 @@
 from .models.projects import ProjectParams
 from .models.sending_domains import CreateSendingDomainParams
 from .models.sending_domains import SendSetupInstructionsParams
+from .models.stats import StatsFilterParams
 from .models.templates import CreateEmailTemplateParams
 from .models.templates import UpdateEmailTemplateParams

mailtrap/api/general.py

@@ -24,3 +24,4 @@ def billing(self) -> BillingApi:
     @property
     def permissions(self) -> PermissionsApi:
         return PermissionsApi(client=self._client)
+

mailtrap/api/resources/stats.py

@@ -0,0 +1,73 @@
+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
+
+GroupKey = Literal["domains", "categories", "email_service_providers", "date"]
+
+_GROUP_KEYS = {
+    "domains": "sending_domain_id",
+    "categories": "category",
+    "email_service_providers": "email_service_provider",
+    "date": "date",
+}
+
+
+class StatsApi:
+    def __init__(self, client: HttpClient) -> None:
+        self._client = client
+
+    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,
+        )
+        return SendingStats(**response)
+
+    def by_domain(
+        self, account_id: int, params: StatsFilterParams
+    ) -> list[SendingStatGroup]:
+        """Get sending stats grouped by domains."""
+        return self._grouped_stats(account_id, "domains", params)
+
+    def by_category(
+        self, account_id: int, params: StatsFilterParams
+    ) -> list[SendingStatGroup]:
+        """Get sending stats grouped by categories."""
+        return self._grouped_stats(account_id, "categories", params)
+
+    def by_email_service_provider(
+        self, account_id: int, params: StatsFilterParams
+    ) -> list[SendingStatGroup]:
+        """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]:
+        """Get sending stats grouped by date."""
+        return self._grouped_stats(account_id, "date", params)
+
+    def _grouped_stats(
+        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]
+
+        return [
+            SendingStatGroup(
+                name=group_key,
+                value=item[group_key],
+                stats=SendingStats(**item["stats"]),
+            )
+            for item in response
+        ]
+
+    @staticmethod
+    def _base_path(account_id: int) -> str:
+        return f"/api/accounts/{account_id}/stats"

mailtrap/client.py

@@ -8,6 +8,7 @@
 
 from mailtrap.api.contacts import ContactsBaseApi
 from mailtrap.api.general import GeneralApi
+from mailtrap.api.resources.stats import StatsApi
 from mailtrap.api.sending import SendingApi
 from mailtrap.api.sending_domains import SendingDomainsBaseApi
 from mailtrap.api.suppressions import SuppressionsBaseApi
@@ -116,6 +117,12 @@ def sending_api(self) -> SendingApi:
         http_client = HttpClient(host=self._sending_api_host, headers=self.headers)
         return SendingApi(client=http_client, inbox_id=self.inbox_id)
 
+    @property
+    def stats_api(self) -> StatsApi:
+        return StatsApi(
+            client=HttpClient(host=GENERAL_HOST, headers=self.headers),
+        )
+
     def send(self, mail: BaseMail) -> SEND_ENDPOINT_RESPONSE:
         sending_response = self.sending_api.send(mail)
         return cast(

mailtrap/models/common.py

@@ -18,6 +18,14 @@ def api_data(self: T) -> dict[str, Any]:
             TypeAdapter(type(self)).dump_python(self, by_alias=True, exclude_none=True),
         )
 
+    @property
+    def api_query_params(self: T) -> dict[str, Any]:
+        data = self.api_data
+        for key, value in list(data.items()):
+            if isinstance(value, list):
+                data[f"{key}[]"] = data.pop(key)
+        return data
+
 
 @dataclass
 class DeletedObject:

mailtrap/models/stats.py

@@ -0,0 +1,37 @@
+from typing import Optional
+from typing import Union
+
+from pydantic.dataclasses import dataclass
+
+from mailtrap.models.common import RequestParams
+
+
+@dataclass
+class SendingStats:
+    delivery_count: int
+    delivery_rate: float
+    bounce_count: int
+    bounce_rate: float
+    open_count: int
+    open_rate: float
+    click_count: int
+    click_rate: float
+    spam_count: int
+    spam_rate: float
+
+
+@dataclass
+class SendingStatGroup:
+    name: str
+    value: Union[str, int]
+    stats: SendingStats
+
+
+@dataclass
+class StatsFilterParams(RequestParams):
+    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

@@ -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"]