Add tracking opt-outs and create-suppression endpoints

README.md

@@ -240,8 +240,9 @@ Email API:
 - Batch send with Template (Transactional) – [`batch/transactional_template.php`](examples/batch/transactional_template.php)
 - Batch send with Template (Bulk) – [`batch/bulk_template.php`](examples/batch/bulk_template.php)
 - Sending domain management CRUD – [`sending-domains/all.php`](examples/sending-domains/all.php)
-- Sending domain company info – [`company-info/all.php`](examples/company-info/all.php)
-- Suppressions (find & delete) – [`sending/suppressions.php`](examples/sending/suppressions.php)
+- Sending domain company info – [`sending-domains/company-info.php`](examples/sending-domains/company-info.php)
+- Suppressions (create, find & delete) – [`sending/suppressions.php`](examples/sending/suppressions.php)
+- Tracking Opt-outs (list, create & delete) – [`sending/tracking-opt-outs.php`](examples/sending/tracking-opt-outs.php)
 - Email Logs (list & get by message ID) – [`sending/email-logs.php`](examples/sending/email-logs.php)
 
 Email Sandbox (Testing):

examples/README.md

@@ -16,6 +16,7 @@ Central index of runnable example scripts demonstrating Mailtrap PHP SDK feature
 | Full featured send (headers, vars, attachments) | [`sending/all.php`](sending/all.php) |
 | Send using a template (transactional stream) | [`sending/template.php`](sending/template.php) |
 | Suppressions API usage | [`sending/suppressions.php`](sending/suppressions.php) |
+| Tracking Opt-outs API usage | [`sending/tracking-opt-outs.php`](sending/tracking-opt-outs.php) |
 | Bulk API single send (stream selection) | [`bulk/bulk.php`](bulk/bulk.php) |
 | Bulk API template send | [`bulk/bulk_template.php`](bulk/bulk_template.php) |
 
@@ -65,7 +66,7 @@ Central index of runnable example scripts demonstrating Mailtrap PHP SDK feature
 |---------|------|
 | Templates CRUD | [`templates/all.php`](templates/all.php) |
 | Sending domains CRUD | [`sending-domains/all.php`](sending-domains/all.php) |
-| Sending domain company info | [`company-info/all.php`](company-info/all.php) |
+| Sending domain company info | [`sending-domains/company-info.php`](sending-domains/company-info.php) |
 
 ### General API
 

examples/sending/suppressions.php

@@ -3,6 +3,9 @@
 declare(strict_types=1);
 
 use Mailtrap\Config;
+use Mailtrap\DTO\Request\Suppression\CreateSuppression;
+use Mailtrap\DTO\Request\Suppression\Suppression;
+use Mailtrap\DTO\Request\Suppression\SuppressionsFilter;
 use Mailtrap\Helper\ResponseHelper;
 use Mailtrap\MailtrapSendingClient;
 
@@ -24,6 +27,38 @@
     // OR get suppressions by email
     $response = $mailtrapSuppression->getSuppressions('some_email@mail.com');
 
+    // OR filter by email and creation time
+    $response = $mailtrapSuppression->getSuppressions(
+        new SuppressionsFilter(
+            email: 'some_email@mail.com',
+            startTime: '2025-01-01T00:00:00Z',
+            endTime: '2025-12-31T23:59:59Z'
+        )
+    );
+
+    // Print the response body (array)
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), PHP_EOL;
+}
+
+
+/**
+ * Create Suppression.
+ *
+ * POST https://mailtrap.io/api/accounts/{account_id}/suppressions
+ */
+try {
+    // `type` is optional and defaults to "manual import" when omitted.
+    $response = $mailtrapSuppression->createSuppression(
+        new CreateSuppression(
+            email: 'some_email@mail.com',
+            domainId: (int) $_ENV['MAILTRAP_DOMAIN_ID'],
+            sendingStream: Suppression::SENDING_STREAM_TRANSACTIONAL,
+            type: Suppression::TYPE_MANUAL_IMPORT
+        )
+    );
+
     // Print the response body (array)
     var_dump(ResponseHelper::toArray($response));
 } catch (Exception $e) {

examples/sending/tracking-opt-outs.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+use Mailtrap\Config;
+use Mailtrap\DTO\Request\TrackingOptOut\CreateTrackingOptOut;
+use Mailtrap\DTO\Request\TrackingOptOut\TrackingOptOutsFilter;
+use Mailtrap\Helper\ResponseHelper;
+use Mailtrap\MailtrapSendingClient;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+$config = new Config($_ENV['MAILTRAP_API_KEY']); #your API token from here https://mailtrap.io/api-tokens
+$domainId = (int) $_ENV['MAILTRAP_DOMAIN_ID'];
+
+$trackingOptOuts = (new MailtrapSendingClient($config))->trackingOptOuts();
+
+/**
+ * Create a tracking opt-out
+ *
+ * POST https://mailtrap.io/api/tracking_opt_outs
+ */
+try {
+    $response = $trackingOptOuts->createTrackingOptOut(
+        new CreateTrackingOptOut(email: 'tracked@example.com', domainId: $domainId)
+    );
+
+    // print the response body (array)
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), "\n";
+}
+
+
+/**
+ * Get tracking opt-outs
+ *
+ * GET https://mailtrap.io/api/tracking_opt_outs
+ *
+ * Returns up to 1000 records per request. When `last_id` is not null, pass it
+ * back as a filter to fetch the next page.
+ */
+try {
+    $response = $trackingOptOuts->getTrackingOptOuts();
+
+    // OR filter by email and creation time
+    $response = $trackingOptOuts->getTrackingOptOuts(
+        new TrackingOptOutsFilter(
+            email: 'tracked@example.com',
+            startTime: '2025-01-01T00:00:00Z',
+            endTime: '2025-12-31T23:59:59Z'
+        )
+    );
+
+    // print the response body (array)
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), "\n";
+}
+
+
+/**
+ * Delete a tracking opt-out
+ *
+ * DELETE https://mailtrap.io/api/tracking_opt_outs/{tracking_opt_out_id}
+ */
+try {
+    $response = $trackingOptOuts->deleteTrackingOptOut('64d71bf3-1276-417b-86e1-8e66f138acfe');
+
+    // print the response body (array) — the deleted record
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), "\n";
+}

src/Api/Sending/Suppression.php

@@ -6,6 +6,8 @@
 
 use Mailtrap\Api\AbstractApi;
 use Mailtrap\ConfigInterface;
+use Mailtrap\DTO\Request\Suppression\CreateSuppression;
+use Mailtrap\DTO\Request\Suppression\SuppressionsFilter;
 use Psr\Http\Message\ResponseInterface;
 
 /**
@@ -19,17 +21,38 @@ public function __construct(ConfigInterface $config, private int $accountId)
     }
 
     /**
-     * List and search suppressions by email. The endpoint returns up to 1000 suppressions per request.
+     * List and search suppressions. The endpoint returns up to 1000 suppressions per request.
      *
-     * @param string|null $email The email to filter suppressions by, or null to get all.
+     * @param string|SuppressionsFilter|null $filter Either an email to filter by, a
+     *                                               SuppressionsFilter for the full set of
+     *                                               filters, or null to get all.
      * @return ResponseInterface
      */
-    public function getSuppressions(?string $email = null): ResponseInterface
+    public function getSuppressions(string|SuppressionsFilter|null $filter = null): ResponseInterface
+    {
+        $queryParams = match (true) {
+            $filter instanceof SuppressionsFilter => $filter->toArray(),
+            is_string($filter) && $filter !== '' => ['email' => $filter],
+            default => [],
+        };
+
+        return $this->handleResponse(
+            $this->httpGet($this->getBasePath(), $queryParams)
+        );
+    }
+
+    /**
+     * Add an email address to the account's suppression list.
+     *
+     * @param CreateSuppression $suppression
+     * @return ResponseInterface
+     */
+    public function createSuppression(CreateSuppression $suppression): ResponseInterface
     {
         return $this->handleResponse(
-            $this->httpGet(
-                $this->getBasePath(),
-                $email ? ['email' => $email] : []
+            $this->httpPost(
+                path: $this->getBasePath(),
+                body: $suppression->toArray()
             )
         );
     }

src/Api/Sending/TrackingOptOut.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\Api\Sending;
+
+use Mailtrap\Api\AbstractApi;
+use Mailtrap\DTO\Request\TrackingOptOut\CreateTrackingOptOut;
+use Mailtrap\DTO\Request\TrackingOptOut\TrackingOptOutsFilter;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Class TrackingOptOut
+ */
+class TrackingOptOut extends AbstractApi implements SendingInterface
+{
+    /**
+     * List email addresses that have opted out of open and click tracking.
+     * The endpoint returns up to 1000 records per request; pass the previous
+     * response's last_id to fetch the next page.
+     *
+     * @param TrackingOptOutsFilter|null $filter
+     * @return ResponseInterface
+     */
+    public function getTrackingOptOuts(?TrackingOptOutsFilter $filter = null): ResponseInterface
+    {
+        return $this->handleResponse(
+            $this->httpGet(
+                $this->getBasePath(),
+                $filter ? $filter->toArray() : []
+            )
+        );
+    }
+
+    /**
+     * Add an email address to the tracking opt-out list for a sending domain.
+     *
+     * @param CreateTrackingOptOut $trackingOptOut
+     * @return ResponseInterface
+     */
+    public function createTrackingOptOut(CreateTrackingOptOut $trackingOptOut): ResponseInterface
+    {
+        return $this->handleResponse(
+            $this->httpPost(
+                path: $this->getBasePath(),
+                body: $trackingOptOut->toArray()
+            )
+        );
+    }
+
+    /**
+     * Remove an email address from the tracking opt-out list so open and click
+     * tracking can apply again.
+     *
+     * @param string $trackingOptOutId
+     * @return ResponseInterface
+     */
+    public function deleteTrackingOptOut(string $trackingOptOutId): ResponseInterface
+    {
+        return $this->handleResponse(
+            $this->httpDelete(
+                sprintf('%s/%s', $this->getBasePath(), $trackingOptOutId)
+            )
+        );
+    }
+
+    private function getBasePath(): string
+    {
+        return sprintf('%s/api/tracking_opt_outs', $this->getHost());
+    }
+}

src/DTO/Request/Suppression/CreateSuppression.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Suppression;
+
+/**
+ * Class CreateSuppression
+ *
+ * Adds an email address to the account's suppression list.
+ */
+final class CreateSuppression implements SuppressionInterface
+{
+    /**
+     * @param string      $email         Email address to suppress
+     * @param int         $domainId      ID of the domain to suppress this email for
+     * @param string      $sendingStream One of Suppression::SENDING_STREAM_*
+     * @param string|null $type          One of Suppression::TYPE_*. The API defaults to
+     *                                   "manual import" when omitted.
+     */
+    public function __construct(
+        private string $email,
+        private int $domainId,
+        private string $sendingStream,
+        private ?string $type = null,
+    ) {
+    }
+
+    public function toArray(): array
+    {
+        $payload = [
+            'email' => $this->email,
+            'domain_id' => $this->domainId,
+            'sending_stream' => $this->sendingStream,
+        ];
+
+        if ($this->type !== null) {
+            $payload['type'] = $this->type;
+        }
+
+        return $payload;
+    }
+}

src/DTO/Request/Suppression/Suppression.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Suppression;
+
+/**
+ * Suppression vocabulary: sending streams and suppression types.
+ */
+final class Suppression
+{
+    public const SENDING_STREAM_TRANSACTIONAL = 'transactional';
+    public const SENDING_STREAM_BULK = 'bulk';
+
+    public const TYPE_HARD_BOUNCE = 'hard bounce';
+    public const TYPE_UNSUBSCRIPTION = 'unsubscription';
+    public const TYPE_SPAM_COMPLAINT = 'spam complaint';
+    public const TYPE_MANUAL_IMPORT = 'manual import';
+
+    private function __construct()
+    {
+    }
+}

src/DTO/Request/Suppression/SuppressionInterface.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Suppression;
+
+use Mailtrap\DTO\Request\RequestInterface;
+
+interface SuppressionInterface extends RequestInterface
+{
+}