Add Stats API

CHANGELOG.md

@@ -1,3 +1,6 @@
+## [3.10.0] - 2026-03-06
+- Add Stats API with get, byDomains, byCategories, byEmailServiceProviders, byDate endpoints
+
 ## [3.9.1] - 2025-10-27
 - Improve README
 

examples/sending/stats.php

@@ -0,0 +1,97 @@
+<?php
+
+use Mailtrap\Config;
+use Mailtrap\Helper\ResponseHelper;
+use Mailtrap\MailtrapSendingClient;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$accountId = (int) $_ENV['MAILTRAP_ACCOUNT_ID'];
+$config = new Config($_ENV['MAILTRAP_API_KEY']); #your API token from here https://mailtrap.io/api-tokens
+$stats = (new MailtrapSendingClient($config))->stats($accountId);
+
+/**
+ * Get aggregated sending stats.
+ *
+ * GET https://mailtrap.io/api/accounts/{account_id}/stats
+ */
+try {
+    $response = $stats->get('2026-01-01', '2026-01-31');
+
+    // print the response body (array)
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), PHP_EOL;
+}
+
+/**
+ * Get aggregated sending stats with filters.
+ *
+ * GET https://mailtrap.io/api/accounts/{account_id}/stats
+ */
+try {
+    $response = $stats->get(
+        '2026-01-01',
+        '2026-01-31',
+        sendingDomainIds: [1, 2],
+        sendingStreams: ['transactional'],
+        categories: ['Transactional', 'Marketing'],
+        emailServiceProviders: ['Gmail', 'Yahoo']
+    );
+
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), PHP_EOL;
+}
+
+/**
+ * Get sending stats grouped by domains.
+ *
+ * GET https://mailtrap.io/api/accounts/{account_id}/stats/domains
+ */
+try {
+    $response = $stats->byDomains('2026-01-01', '2026-01-31');
+
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), PHP_EOL;
+}
+
+/**
+ * Get sending stats grouped by categories.
+ *
+ * GET https://mailtrap.io/api/accounts/{account_id}/stats/categories
+ */
+try {
+    $response = $stats->byCategories('2026-01-01', '2026-01-31');
+
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), PHP_EOL;
+}
+
+/**
+ * Get sending stats grouped by email service providers.
+ *
+ * GET https://mailtrap.io/api/accounts/{account_id}/stats/email_service_providers
+ */
+try {
+    $response = $stats->byEmailServiceProviders('2026-01-01', '2026-01-31');
+
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), PHP_EOL;
+}
+
+/**
+ * Get sending stats grouped by date.
+ *
+ * GET https://mailtrap.io/api/accounts/{account_id}/stats/date
+ */
+try {
+    $response = $stats->byDate('2026-01-01', '2026-01-31');
+
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), PHP_EOL;
+}

src/Api/Sending/Stats.php

@@ -0,0 +1,192 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\Api\Sending;
+
+use Mailtrap\Api\AbstractApi;
+use Mailtrap\ConfigInterface;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Class Stats
+ */
+class Stats extends AbstractApi implements SendingInterface
+{
+    public function __construct(ConfigInterface $config, private int $accountId)
+    {
+        parent::__construct($config);
+    }
+
+    /**
+     * Get aggregated sending stats.
+     *
+     * @param string $startDate
+     * @param string $endDate
+     * @param array  $sendingDomainIds
+     * @param array  $sendingStreams
+     * @param array  $categories
+     * @param array  $emailServiceProviders
+     *
+     * @return ResponseInterface
+     */
+    public function get(
+        string $startDate,
+        string $endDate,
+        array $sendingDomainIds = [],
+        array $sendingStreams = [],
+        array $categories = [],
+        array $emailServiceProviders = []
+    ): ResponseInterface {
+        return $this->handleResponse($this->httpGet(
+            $this->getBasePath(),
+            $this->buildQueryParams($startDate, $endDate, $sendingDomainIds, $sendingStreams, $categories, $emailServiceProviders)
+        ));
+    }
+
+    /**
+     * Get sending stats grouped by domains.
+     *
+     * @param string $startDate
+     * @param string $endDate
+     * @param array  $sendingDomainIds
+     * @param array  $sendingStreams
+     * @param array  $categories
+     * @param array  $emailServiceProviders
+     *
+     * @return ResponseInterface
+     */
+    public function byDomains(
+        string $startDate,
+        string $endDate,
+        array $sendingDomainIds = [],
+        array $sendingStreams = [],
+        array $categories = [],
+        array $emailServiceProviders = []
+    ): ResponseInterface {
+        return $this->handleResponse($this->httpGet(
+            $this->getBasePath() . '/domains',
+            $this->buildQueryParams($startDate, $endDate, $sendingDomainIds, $sendingStreams, $categories, $emailServiceProviders)
+        ));
+    }
+
+    /**
+     * Get sending stats grouped by categories.
+     *
+     * @param string $startDate
+     * @param string $endDate
+     * @param array  $sendingDomainIds
+     * @param array  $sendingStreams
+     * @param array  $categories
+     * @param array  $emailServiceProviders
+     *
+     * @return ResponseInterface
+     */
+    public function byCategories(
+        string $startDate,
+        string $endDate,
+        array $sendingDomainIds = [],
+        array $sendingStreams = [],
+        array $categories = [],
+        array $emailServiceProviders = []
+    ): ResponseInterface {
+        return $this->handleResponse($this->httpGet(
+            $this->getBasePath() . '/categories',
+            $this->buildQueryParams($startDate, $endDate, $sendingDomainIds, $sendingStreams, $categories, $emailServiceProviders)
+        ));
+    }
+
+    /**
+     * Get sending stats grouped by email service providers.
+     *
+     * @param string $startDate
+     * @param string $endDate
+     * @param array  $sendingDomainIds
+     * @param array  $sendingStreams
+     * @param array  $categories
+     * @param array  $emailServiceProviders
+     *
+     * @return ResponseInterface
+     */
+    public function byEmailServiceProviders(
+        string $startDate,
+        string $endDate,
+        array $sendingDomainIds = [],
+        array $sendingStreams = [],
+        array $categories = [],
+        array $emailServiceProviders = []
+    ): ResponseInterface {
+        return $this->handleResponse($this->httpGet(
+            $this->getBasePath() . '/email_service_providers',
+            $this->buildQueryParams($startDate, $endDate, $sendingDomainIds, $sendingStreams, $categories, $emailServiceProviders)
+        ));
+    }
+
+    /**
+     * Get sending stats grouped by date.
+     *
+     * @param string $startDate
+     * @param string $endDate
+     * @param array  $sendingDomainIds
+     * @param array  $sendingStreams
+     * @param array  $categories
+     * @param array  $emailServiceProviders
+     *
+     * @return ResponseInterface
+     */
+    public function byDate(
+        string $startDate,
+        string $endDate,
+        array $sendingDomainIds = [],
+        array $sendingStreams = [],
+        array $categories = [],
+        array $emailServiceProviders = []
+    ): ResponseInterface {
+        return $this->handleResponse($this->httpGet(
+            $this->getBasePath() . '/date',
+            $this->buildQueryParams($startDate, $endDate, $sendingDomainIds, $sendingStreams, $categories, $emailServiceProviders)
+        ));
+    }
+
+    public function getAccountId(): int
+    {
+        return $this->accountId;
+    }
+
+    private function getBasePath(): string
+    {
+        return sprintf('%s/api/accounts/%s/stats', $this->getHost(), $this->getAccountId());
+    }
+
+    private function buildQueryParams(
+        string $startDate,
+        string $endDate,
+        array $sendingDomainIds,
+        array $sendingStreams,
+        array $categories,
+        array $emailServiceProviders
+    ): array {
+        $params = [
+            'start_date' => $startDate,
+            'end_date' => $endDate,
+        ];
+
+        if (count($sendingDomainIds) > 0) {
+            $params['sending_domain_ids'] = $sendingDomainIds;
+        }
+
+        if (count($sendingStreams) > 0) {
+            $params['sending_streams'] = $sendingStreams;
+        }
+
+        if (count($categories) > 0) {
+            $params['categories'] = $categories;
+        }
+
+        if (count($emailServiceProviders) > 0) {
+            $params['email_service_providers'] = $emailServiceProviders;
+        }
+
+        return $params;
+    }
+}

src/MailtrapSendingClient.php

@@ -8,6 +8,7 @@
  * @method  Api\Sending\Emails      emails()
  * @method  Api\Sending\Suppression suppressions(int $accountId)
  * @method  Api\Sending\Domain      domains(int $accountId)
+ * @method  Api\Sending\Stats       stats(int $accountId)
  *
  * Class MailtrapSendingClient
  */
@@ -17,5 +18,6 @@ final class MailtrapSendingClient extends AbstractMailtrapClient implements Emai
         'emails' => Api\Sending\Emails::class,
         'suppressions' => Api\Sending\Suppression::class,
         'domains' => Api\Sending\Domain::class,
+        'stats' => Api\Sending\Stats::class,
     ];
 }