Add Stats API with get, by_domains, by_categories, by_email_service_providers, by_date endpoints

Also adds api_query_params to RequestParams for automatic [] serialization of list query params.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: piobeny

examples/general/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.general_api.stats
+
+
+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_domains(account_id: int) -> list[SendingStatGroup]:
+    params = StatsFilterParams(start_date="2026-01-01", end_date="2026-01-31")
+    return stats_api.by_domains(account_id=account_id, params=params)
+
+
+def get_stats_by_categories(account_id: int) -> list[SendingStatGroup]:
+    params = StatsFilterParams(start_date="2026-01-01", end_date="2026-01-31")
+    return stats_api.by_categories(account_id=account_id, params=params)
+
+
+def get_stats_by_email_service_providers(account_id: int) -> list[SendingStatGroup]:
+    params = StatsFilterParams(start_date="2026-01-01", end_date="2026-01-31")
+    return stats_api.by_email_service_providers(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=["Transactional", "Marketing"],
+        email_service_providers=["Gmail", "Yahoo"],
+    )
+    return stats_api.get(account_id=account_id, params=params)
+
+
+def get_stats_by_domains_with_filters(account_id: int) -> list[SendingStatGroup]:
+    params = StatsFilterParams(
+        start_date="2026-01-01",
+        end_date="2026-01-31",
+        sending_streams=["transactional"],
+        categories=["Transactional"],
+    )
+    return stats_api.by_domains(account_id=account_id, params=params)
+
+
+if __name__ == "__main__":
+    print(get_stats(ACCOUNT_ID))
+    print(get_stats_by_domains(ACCOUNT_ID))
+    print(get_stats_by_categories(ACCOUNT_ID))
+    print(get_stats_by_email_service_providers(ACCOUNT_ID))
+    print(get_stats_by_date(ACCOUNT_ID))
+    print(get_stats_with_filters(ACCOUNT_ID))
+    print(get_stats_by_domains_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

@@ -2,6 +2,7 @@
 from mailtrap.api.resources.accounts import AccountsApi
 from mailtrap.api.resources.billing import BillingApi
 from mailtrap.api.resources.permissions import PermissionsApi
+from mailtrap.api.resources.stats import StatsApi
 from mailtrap.http import HttpClient
 
 
@@ -24,3 +25,7 @@ def billing(self) -> BillingApi:
     @property
     def permissions(self) -> PermissionsApi:
         return PermissionsApi(client=self._client)
+
+    @property
+    def stats(self) -> StatsApi:
+        return StatsApi(client=self._client)

mailtrap/api/resources/stats.py

@@ -0,0 +1,60 @@
+from mailtrap.http import HttpClient
+from mailtrap.models.stats import SendingStatGroup
+from mailtrap.models.stats import SendingStats
+from mailtrap.models.stats import StatsFilterParams
+
+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_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]:
+        """Get sending stats grouped by categories."""
+        return self._grouped_stats(account_id, "categories", params)
+
+    def by_email_service_providers(
+        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: str, 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/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: 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