Add contact event functionality

CHANGELOG.md

@@ -1,3 +1,6 @@
+## [3.8.0] - 2025-09-22
+- Add Create Contact event API functionality
+
 ## [3.7.0] - 2025-09-15
 - Add Sending Domains API functionality
 - Add current billing cycle usage

README.md

@@ -22,6 +22,7 @@ Currently with this SDK you can:
   - Send an email (Transactional and Bulk streams)
   - Send an email with a Template
   - Send a batch of emails (Transactional and Bulk streams)
+  - Sending domain management CRUD
 - Email Sandbox
   - Send an email
   - Send an email with a template
@@ -34,9 +35,11 @@ Currently with this SDK you can:
   - Contacts CRUD
   - Lists CRUD
   - Import
+  - Events
 - General
   - Templates CRUD
   - Suppressions management (find and delete)
+  - Billing info
 
 
 ## Installation

examples/general/contacts.php

@@ -2,6 +2,7 @@
 
 use Mailtrap\Config;
 use Mailtrap\DTO\Request\Contact\CreateContact;
+use Mailtrap\DTO\Request\Contact\CreateContactEvent;
 use Mailtrap\DTO\Request\Contact\ImportContact;
 use Mailtrap\DTO\Request\Contact\UpdateContact;
 use Mailtrap\Helper\ResponseHelper;
@@ -320,3 +321,30 @@
 } catch (Exception $e) {
     echo 'Caught exception: ',  $e->getMessage(), PHP_EOL;
 }
+
+
+/**
+ * Create a new Contact Event
+ *
+ * POST https://mailtrap.io/api/accounts/{account_id}/contacts/{contact_identifier}/events
+ */
+try {
+    // Create event using contact email
+    $response = $contacts->createContactEvent(
+        '[email protected]', // Contact identifier (email or UUID)
+        CreateContactEvent::init(
+            'UserLogin',
+            [
+                'user_id' => 101,
+                'user_name' => 'John Smith',
+                'is_active' => true,
+                'last_seen' => null
+            ]
+        )
+    );
+
+    // print the response body (array)
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), PHP_EOL;
+}

src/Api/General/Contact.php

@@ -7,6 +7,7 @@
 use Mailtrap\Api\AbstractApi;
 use Mailtrap\ConfigInterface;
 use Mailtrap\DTO\Request\Contact\CreateContact;
+use Mailtrap\DTO\Request\Contact\CreateContactEvent;
 use Mailtrap\DTO\Request\Contact\ImportContact;
 use Mailtrap\DTO\Request\Contact\UpdateContact;
 use Mailtrap\Exception\InvalidArgumentException;
@@ -290,6 +291,23 @@ public function getContactImport(int $importId): ResponseInterface
         );
     }
 
+    /**
+     * Create a new Contact Event.
+     *
+     * @param string $contactIdentifier Contact ID (UUID) or email
+     * @param CreateContactEvent $event
+     * @return ResponseInterface
+     */
+    public function createContactEvent(string $contactIdentifier, CreateContactEvent $event): ResponseInterface
+    {
+        return $this->handleResponse(
+            $this->httpPost(
+                path: $this->getBasePath() . '/' . urlencode($contactIdentifier) . '/events',
+                body: $event->toArray()
+            )
+        );
+    }
+
     public function getAccountId(): int
     {
         return $this->accountId;

src/DTO/Request/Contact/CreateContactEvent.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Mailtrap\DTO\Request\Contact;
+
+use Mailtrap\DTO\Request\RequestInterface;
+
+/**
+ * Class CreateContactEvent
+ */
+final class CreateContactEvent implements RequestInterface
+{
+    public function __construct(
+        private string $name,
+        private array $params = []
+    ) {
+    }
+
+    public static function init(string $name, array $params = []): self
+    {
+        return new self($name, $params);
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function getParams(): array
+    {
+        return $this->params;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'name' => $this->getName(),
+            'params' => $this->getParams(),
+        ];
+    }
+}