Add Stats API

[piobeny]

Motivation

• Add support for the Email Sending Stats API (/api/accounts/{account_id}/stats) to the PHP SDK, enabling users to retrieve aggregated email sending statistics.

Changes

• Add Stats class extending AbstractApi with 5 methods: get, byDomains, byCategories, byEmailServiceProviders, byDate
• Add query param handling for array filters (sending_domain_ids, sending_streams, categories, email_service_providers)
• Add usage example in examples/sending/stats.php
• Update README with Stats API reference
• Update CHANGELOG with v3.10.0 entry

How to test

• $stats->get($startDate, $endDate) with different parameters (sendingDomainIds, sendingStreams, categories, emailServiceProviders)
• Test grouped endpoints (byDomains, byCategories, byEmailServiceProviders, byDate) with filters

Examples

use Mailtrap\Config;
use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapSendingClient;

$config = new Config('api_key');
$stats = (new MailtrapSendingClient($config))->stats($accountId);

// Get aggregated stats
$response = $stats->get('2026-01-01', '2026-01-31');
var_dump(ResponseHelper::toArray($response));

// Get stats with optional filters
$response = $stats->get(
    '2026-01-01',
    '2026-01-31',
    sendingDomainIds: [1, 2],
    sendingStreams: ['transactional'],
    categories: ['Welcome email'],
    emailServiceProviders: ['Gmail', 'Yahoo']
);

// Get stats grouped by date
$response = $stats->byDate('2026-01-01', '2026-01-02');

// Get stats grouped by categories
$response = $stats->byCategories('2026-01-01', '2026-01-02');

// Get stats grouped by email service providers with filters
$response = $stats->byEmailServiceProviders(
    '2026-01-01',
    '2026-01-02',
    categories: ['Welcome email']
);

// Get stats grouped by domains with filters
$response = $stats->byDomains(
    '2026-01-01',
    '2026-01-02',
    categories: ['Welcome email'],
    emailServiceProviders: ['Google']
);