Add inbound forward rules and threads search

README.md

@@ -259,7 +259,8 @@ Inbound Email API:
 - Folder management CRUD – [`inbound/folders.php`](examples/inbound/folders.php)
 - Inbox management CRUD – [`inbound/inboxes.php`](examples/inbound/inboxes.php)
 - Message management (list / get / reply / reply-all / forward / delete) – [`inbound/messages.php`](examples/inbound/messages.php)
-- Thread management (list / get / delete) – [`inbound/threads.php`](examples/inbound/threads.php)
+- Thread management (list / search / get / delete) – [`inbound/threads.php`](examples/inbound/threads.php)
+- Forward rule management CRUD – [`inbound/forward-rules.php`](examples/inbound/forward-rules.php)
 
 Contact management:
 - Contacts CRUD & listing – [`contacts/all.php`](examples/contacts/all.php)

examples/README.md

@@ -49,7 +49,8 @@ Central index of runnable example scripts demonstrating Mailtrap PHP SDK feature
 | Folder CRUD / listing | [`inbound/folders.php`](inbound/folders.php) |
 | Inbox CRUD / listing | [`inbound/inboxes.php`](inbound/inboxes.php) |
 | Message list / get / reply / reply-all / forward / delete | [`inbound/messages.php`](inbound/messages.php) |
-| Thread list / get / delete | [`inbound/threads.php`](inbound/threads.php) |
+| Thread list / search / get / delete | [`inbound/threads.php`](inbound/threads.php) |
+| Forward rule CRUD / listing | [`inbound/forward-rules.php`](inbound/forward-rules.php) |
 
 ### Contact Management
 

examples/inbound/forward-rules.php

@@ -0,0 +1,99 @@
+<?php
+
+use Mailtrap\Config;
+use Mailtrap\DTO\Request\Inbound\CreateInboundForwardRule;
+use Mailtrap\DTO\Request\Inbound\InboundForwardRule;
+use Mailtrap\DTO\Request\Inbound\InboundForwardRuleCondition;
+use Mailtrap\DTO\Request\Inbound\InboundForwardRuleDestination;
+use Mailtrap\DTO\Request\Inbound\UpdateInboundForwardRule;
+use Mailtrap\Helper\ResponseHelper;
+use Mailtrap\MailtrapInboundClient;
+
+require __DIR__ . '/../../vendor/autoload.php';
+
+$config = new Config($_ENV['MAILTRAP_API_KEY']); #your API token from here https://mailtrap.io/api-tokens
+
+$inboxId = (int) ($_ENV['MAILTRAP_INBOUND_INBOX_ID'] ?? 0);
+$ruleId = (int) ($_ENV['MAILTRAP_INBOUND_FORWARD_RULE_ID'] ?? 0);
+
+$forwardRules = (new MailtrapInboundClient($config))->forwardRules($inboxId);
+
+/**
+ * List the inbox's forward rules.
+ *
+ * GET https://mailtrap.io/api/inbound/inboxes/{inbox_id}/forward_rules
+ */
+try {
+    $response = $forwardRules->getList();
+
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), "\n";
+}
+
+/**
+ * Create a forward rule.
+ *
+ * POST https://mailtrap.io/api/inbound/inboxes/{inbox_id}/forward_rules
+ */
+try {
+    $response = $forwardRules->create(new CreateInboundForwardRule(
+        name: 'Copy billing mail to finance',
+        conditions: [
+            new InboundForwardRuleCondition(
+                matchType: InboundForwardRule::MATCH_TYPE_SENDER,
+                operator: InboundForwardRule::OPERATOR_ENDS_WITH,
+                value: '@billing.example.com'
+            ),
+        ],
+        destinations: [new InboundForwardRuleDestination('finance@example.com')],
+    ));
+
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), "\n";
+}
+
+/**
+ * Get a forward rule by ID.
+ *
+ * GET https://mailtrap.io/api/inbound/inboxes/{inbox_id}/forward_rules/{id}
+ */
+try {
+    $response = $forwardRules->getById($ruleId);
+
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), "\n";
+}
+
+/**
+ * Update a forward rule's destinations.
+ *
+ * PATCH https://mailtrap.io/api/inbound/inboxes/{inbox_id}/forward_rules/{id}
+ */
+try {
+    $response = $forwardRules->update($ruleId, new UpdateInboundForwardRule(
+        destinations: [
+            new InboundForwardRuleDestination('finance@example.com'),
+            new InboundForwardRuleDestination('accounting@example.com'),
+        ],
+    ));
+
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), "\n";
+}
+
+/**
+ * Delete a forward rule.
+ *
+ * DELETE https://mailtrap.io/api/inbound/inboxes/{inbox_id}/forward_rules/{id}
+ */
+try {
+    $response = $forwardRules->delete($ruleId);
+
+    var_dump($response->getStatusCode());
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), "\n";
+}

examples/inbound/threads.php

@@ -27,6 +27,19 @@
     echo 'Caught exception: ', $e->getMessage(), "\n";
 }
 
+/**
+ * Search threads.
+ *
+ * GET https://mailtrap.io/api/inbound/inboxes/{inbox_id}/threads?search=acme
+ */
+try {
+    $response = $threads->getList(search: 'acme');
+
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), "\n";
+}
+
 /**
  * Get a single thread with its messages embedded.
  *

src/Api/Inbound/ForwardRule.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\Api\Inbound;
+
+use Mailtrap\Api\AbstractApi;
+use Mailtrap\ConfigInterface;
+use Mailtrap\DTO\Request\Inbound\CreateInboundForwardRule;
+use Mailtrap\DTO\Request\Inbound\UpdateInboundForwardRule;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Class ForwardRule
+ *
+ * Forward rules of an inbound inbox.
+ */
+class ForwardRule extends AbstractApi implements InboundInterface
+{
+    public function __construct(ConfigInterface $config, private int $inboxId)
+    {
+        parent::__construct($config);
+    }
+
+    public function getList(): ResponseInterface
+    {
+        return $this->handleResponse($this->httpGet($this->getBasePath()));
+    }
+
+    public function getById(int $ruleId): ResponseInterface
+    {
+        return $this->handleResponse($this->httpGet($this->getBasePath() . '/' . $ruleId));
+    }
+
+    public function create(CreateInboundForwardRule $rule): ResponseInterface
+    {
+        return $this->handleResponse($this->httpPost($this->getBasePath(), [], $rule->toArray()));
+    }
+
+    public function update(int $ruleId, UpdateInboundForwardRule $rule): ResponseInterface
+    {
+        return $this->handleResponse(
+            $this->httpPatch($this->getBasePath() . '/' . $ruleId, [], $rule->toArray())
+        );
+    }
+
+    public function delete(int $ruleId): ResponseInterface
+    {
+        return $this->handleResponse($this->httpDelete($this->getBasePath() . '/' . $ruleId));
+    }
+
+    private function getBasePath(): string
+    {
+        return sprintf('%s/api/inbound/inboxes/%s/forward_rules', $this->getHost(), $this->inboxId);
+    }
+}

src/Api/Inbound/Thread.php

@@ -23,9 +23,17 @@ public function __construct(ConfigInterface $config, private int $inboxId)
     /**
      * List threads. Pass $lastId from a previous response to fetch the next page.
      */
-    public function getList(?string $lastId = null): ResponseInterface
+    public function getList(?string $lastId = null, ?string $search = null): ResponseInterface
     {
-        $parameters = $lastId !== null ? ['last_id' => $lastId] : [];
+        $parameters = [];
+
+        if ($lastId !== null) {
+            $parameters['last_id'] = $lastId;
+        }
+
+        if ($search !== null) {
+            $parameters['search'] = $search;
+        }
 
         return $this->handleResponse($this->httpGet($this->getBasePath(), $parameters));
     }

src/DTO/Request/Inbound/CreateInboundForwardRule.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Inbound;
+
+use Mailtrap\DTO\Request\RequestInterface;
+
+/**
+ * Class CreateInboundForwardRule
+ */
+final class CreateInboundForwardRule implements RequestInterface
+{
+    /**
+     * @param InboundForwardRuleCondition[]|null   $conditions
+     * @param InboundForwardRuleDestination[]|null $destinations
+     */
+    public function __construct(
+        private string $name,
+        private ?array $conditions = null,
+        private ?array $destinations = null,
+    ) {
+    }
+
+    public function toArray(): array
+    {
+        $payload = [
+            'name' => $this->name,
+        ];
+
+        if ($this->conditions !== null) {
+            $payload['conditions'] = array_values(array_map(
+                static fn (InboundForwardRuleCondition $condition): array => $condition->toArray(),
+                $this->conditions
+            ));
+        }
+
+        if ($this->destinations !== null) {
+            $payload['destinations'] = array_values(array_map(
+                static fn (InboundForwardRuleDestination $destination): array => $destination->toArray(),
+                $this->destinations
+            ));
+        }
+
+        return $payload;
+    }
+}

src/DTO/Request/Inbound/InboundForwardRule.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Inbound;
+
+/**
+ * Forward rule vocabulary: match types and operators.
+ */
+final class InboundForwardRule
+{
+    public const MATCH_TYPE_SENDER = 'sender';
+    public const MATCH_TYPE_RECIPIENT = 'recipient';
+    public const MATCH_TYPE_HEADER = 'header';
+
+    public const OPERATOR_EQUAL = 'equal';
+    public const OPERATOR_NOT_EQUAL = 'not_equal';
+    public const OPERATOR_CONTAINS = 'contains';
+    public const OPERATOR_STARTS_WITH = 'starts_with';
+    public const OPERATOR_ENDS_WITH = 'ends_with';
+    public const OPERATOR_EMPTY = 'empty';
+    public const OPERATOR_NOT_EMPTY = 'not_empty';
+
+    public const MATCH_TYPES = [
+        self::MATCH_TYPE_SENDER,
+        self::MATCH_TYPE_RECIPIENT,
+        self::MATCH_TYPE_HEADER,
+    ];
+
+    public const OPERATORS = [
+        self::OPERATOR_EQUAL,
+        self::OPERATOR_NOT_EQUAL,
+        self::OPERATOR_CONTAINS,
+        self::OPERATOR_STARTS_WITH,
+        self::OPERATOR_ENDS_WITH,
+        self::OPERATOR_EMPTY,
+        self::OPERATOR_NOT_EMPTY,
+    ];
+
+    private function __construct()
+    {
+    }
+}

src/DTO/Request/Inbound/InboundForwardRuleCondition.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Inbound;
+
+use Mailtrap\DTO\Request\RequestInterface;
+use Mailtrap\Exception\InvalidArgumentException;
+
+/**
+ * Class InboundForwardRuleCondition
+ */
+final class InboundForwardRuleCondition implements RequestInterface
+{
+    public function __construct(
+        private string $matchType,
+        private string $operator,
+        private ?string $value = null,
+        private ?string $headerKey = null,
+    ) {
+        if (!in_array($matchType, InboundForwardRule::MATCH_TYPES, true)) {
+            throw new InvalidArgumentException(sprintf(
+                '"matchType" must be one of "%s", "%s" given',
+                implode('", "', InboundForwardRule::MATCH_TYPES),
+                $matchType
+            ));
+        }
+
+        if (!in_array($operator, InboundForwardRule::OPERATORS, true)) {
+            throw new InvalidArgumentException(sprintf(
+                '"operator" must be one of "%s", "%s" given',
+                implode('", "', InboundForwardRule::OPERATORS),
+                $operator
+            ));
+        }
+    }
+
+    public function toArray(): array
+    {
+        $payload = [
+            'match_type' => $this->matchType,
+            'operator' => $this->operator,
+        ];
+
+        if ($this->value !== null) {
+            $payload['value'] = $this->value;
+        }
+
+        if ($this->headerKey !== null) {
+            $payload['header_key'] = $this->headerKey;
+        }
+
+        return $payload;
+    }
+}

src/DTO/Request/Inbound/InboundForwardRuleDestination.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Inbound;
+
+use Mailtrap\DTO\Request\RequestInterface;
+
+/**
+ * Class InboundForwardRuleDestination
+ */
+final class InboundForwardRuleDestination implements RequestInterface
+{
+    public function __construct(
+        private string $email,
+    ) {
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'email' => $this->email,
+        ];
+    }
+}