Improve examples

README.md

@@ -228,38 +228,55 @@ try {
 }
 ```
 
-### All usage examples
-
-You can find more examples [here](examples).
-* [General examples](examples/general)
-* [Testing examples](examples/testing)
-* [Sending examples](examples/sending)
-
-## Supported functionality
-
-Currently, with this SDK, you can:
-- Email API/SMTP
-    - 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
-    - Send a batch of emails
-    - Message management
-    - Inbox management
-    - Project management
-- Contact management
-    - Fields CRUD
-    - Contacts CRUD
-    - Lists CRUD
-    - Import/Export
-    - Events
-- General
-    - Templates CRUD
-    - Suppressions management (find and delete)
-    - Billing info
+## Supported functionality & Examples
+
+Email API:
+- Send an email (Transactional stream) – [`sending/minimal.php`](examples/sending/minimal.php)
+- Send an email (Bulk stream) – [`bulk/bulk.php`](examples/bulk/bulk.php)
+- Send an email with a Template (Transactional) – [`sending/template.php`](examples/sending/template.php)
+- Send an email with a Template (Bulk) – [`bulk/bulk_template.php`](examples/bulk/bulk_template.php)
+- Batch send (Transactional) – [`batch/transactional.php`](examples/batch/transactional.php)
+- Batch send (Bulk) – [`batch/bulk.php`](examples/batch/bulk.php)
+- 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)
+
+Email Sandbox (Testing):
+- Send an email (Sandbox) – [`testing/send-mail.php`](examples/testing/send-mail.php)
+- Send an email with a Template (Sandbox) – [`testing/template.php`](examples/testing/template.php)
+- Batch send (Sandbox) – [`batch/sandbox.php`](examples/batch/sandbox.php)
+- Batch send with Template (Sandbox) – [`batch/sandbox_template.php`](examples/batch/sandbox_template.php)
+- Message management CRUD – [`testing/messages.php`](examples/testing/messages.php)
+- Inbox management CRUD – [`testing/inboxes.php`](examples/testing/inboxes.php)
+- Project management CRUD – [`testing/projects.php`](examples/testing/projects.php)
+- Attachments operations – [`testing/attachments.php`](examples/testing/attachments.php)
+
+Contact management:
+- Contacts CRUD & listing – [`contacts/all.php`](examples/contacts/all.php)
+- Contact lists CRUD – [`contact-lists/all.php`](examples/contact-lists/all.php)
+- Custom fields CRUD – [`contact-fields/all.php`](examples/contact-fields/all.php)
+- Import/Export – (no example yet) ← add in future
+- Events – (no example yet) ← add in future
+
+General API:
+- Templates CRUD – [`templates/all.php`](examples/templates/all.php)
+- Suppressions (find & delete) – [`sending/suppressions.php`](examples/sending/suppressions.php)
+- Billing info – [`general/billing.php`](examples/general/billing.php)
+- Accounts info – [`general/accounts.php`](examples/general/accounts.php)
+- Permissions listing – [`general/permissions.php`](examples/general/permissions.php)
+- Users listing – [`general/users.php`](examples/general/users.php)
+
+Framework-specific (quick starts):
+- Laravel transactional send – [`laravel/transactional.php`](examples/laravel/transactional.php)
+- Laravel sandbox send – [`laravel/sandbox.php`](examples/laravel/sandbox.php)
+- Laravel template send – [`laravel/template.php`](examples/laravel/template.php)
+- Laravel bulk send – [`laravel/bulk.php`](examples/laravel/bulk.php)
+- Symfony transactional send – [`symfony/transactional.php`](examples/symfony/transactional.php)
+- Symfony sandbox send – [`symfony/sandbox.php`](examples/symfony/sandbox.php)
+- Symfony template send – [`symfony/template.php`](examples/symfony/template.php)
+- Symfony bulk send – [`symfony/bulk.php`](examples/symfony/bulk.php)
+
+See the full indexed list at [`examples/README.md`](examples/README.md).
 
 ## Contributing
 

examples/README.md

@@ -0,0 +1,85 @@
+# Examples Index
+
+Central index of runnable example scripts demonstrating Mailtrap PHP SDK features. Each script is intentionally minimal; open the file to inspect parameters. Run examples from project root (adjust env vars first).
+
+## Prerequisites
+* Export or place inside the file your ENV variables (MAILTRAP_API_KEY, MAILTRAP_INBOX_ID, etc)
+* Some examples require a verified sending domain (production / bulk / templates).
+
+## Contents
+
+### 1. Sending (Transactional / Bulk Streams)
+| Purpose | File |
+|---------|------|
+| Minimal transactional send | [`sending/minimal.php`](sending/minimal.php) |
+| 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) |
+| Bulk API single send (stream selection) | [`bulk/bulk.php`](bulk/bulk.php) |
+| Bulk API template send | [`bulk/bulk_template.php`](bulk/bulk_template.php) |
+
+### 2. Batch Sending (multiple messages in one call)
+| Purpose | File |
+|---------|------|
+| Transactional batch send | [`batch/transactional.php`](batch/transactional.php) |
+| Transactional batch send (template) | [`batch/transactional_template.php`](batch/transactional_template.php) |
+| Bulk batch send | [`batch/bulk.php`](batch/bulk.php) |
+| Bulk batch send (template) | [`batch/bulk_template.php`](batch/bulk_template.php) |
+| Sandbox batch send | [`batch/sandbox.php`](batch/sandbox.php) |
+| Sandbox batch send (template) | [`batch/sandbox_template.php`](batch/sandbox_template.php) |
+
+### 3. Sandbox (Email Testing)
+| Purpose | File |
+|---------|------|
+| Sandbox transactional send | [`testing/send-mail.php`](testing/send-mail.php) |
+| Sandbox send with template | [`testing/template.php`](testing/template.php) |
+| Manage attachments of a message | [`testing/attachments.php`](testing/attachments.php) |
+| Inbox CRUD / listing | [`testing/inboxes.php`](testing/inboxes.php) |
+| Message CRUD / listing | [`testing/messages.php`](testing/messages.php) |
+| Project CRUD / listing | [`testing/projects.php`](testing/projects.php) |
+
+### 4. Contact Management
+| Purpose | File |
+|---------|------|
+| Contacts CRUD + list | [`contacts/all.php`](contacts/all.php) |
+| Contact lists CRUD | [`contact-lists/all.php`](contact-lists/all.php) |
+| Custom fields CRUD | [`contact-fields/all.php`](contact-fields/all.php) |
+
+### 5. Templates & Domains
+| Purpose | File |
+|---------|------|
+| Templates CRUD | [`templates/all.php`](templates/all.php) |
+| Sending domains CRUD | [`sending-domains/all.php`](sending-domains/all.php) |
+
+### 6. General API
+| Purpose | File |
+|---------|------|
+| Accounts info | [`general/accounts.php`](general/accounts.php) |
+| Billing info | [`general/billing.php`](general/billing.php) |
+| Permissions listing | [`general/permissions.php`](general/permissions.php) |
+| Users listing | [`general/users.php`](general/users.php) |
+
+### 7. Framework Bridges
+| Framework | Files |
+|-----------|-------|
+| Laravel (transactional, sandbox, template, bulk) | [`laravel/transactional.php`](laravel/transactional.php), [`laravel/sandbox.php`](laravel/sandbox.php), [`laravel/template.php`](laravel/template.php), [`laravel/bulk.php`](laravel/bulk.php) |
+| Symfony (transactional, sandbox, template, bulk) | [`symfony/transactional.php`](symfony/transactional.php), [`symfony/sandbox.php`](symfony/sandbox.php), [`symfony/template.php`](symfony/template.php), [`symfony/bulk.php`](symfony/bulk.php) |
+
+### 8. Configuration Utilities
+| Purpose | File |
+|---------|------|
+| Showcase of combined config usage / initialization patterns | [`config/all.php`](config/all.php) |
+
+## Running an Example
+From project root:
+```
+php examples/sending/minimal.php
+```
+For batch examples, ensure the stream (bulk vs transactional vs sandbox) matches your API token and domain verification status.
+
+## Tips
+- Keep secrets out of committed files; rely on environment variables.
+- Template examples require existing template UUIDs in your Mailtrap account.
+- Sandbox examples need `MAILTRAP_INBOX_ID`.
+
+---

examples/batch/bulk.php

@@ -0,0 +1,44 @@
+<?php
+
+use Mailtrap\Helper\ResponseHelper;
+use Mailtrap\MailtrapClient;
+use Mailtrap\Mime\MailtrapEmail;
+use Symfony\Component\Mime\Address;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * Email Batch Sending API (Bulk)
+ *
+ * Batch send email (text, html, text&html, templates).
+ *
+ * Please note that the endpoint will return a 200-level http status, even when sending for individual messages may fail.
+ * Users of this endpoint should check the success and errors for each message in the response (the results are ordered the same as the original messages - requests).
+ * Please note that the endpoint accepts up to 500 messages per API call, and up to 50 MB payload size, including attachments.
+ *
+ * For this example, you need to have ready-to-use sending domain or, a Demo domain that allows sending emails to your own account email.
+ * @see https://help.mailtrap.io/article/69-sending-domain-setup
+ */
+try {
+     $mailtrap = MailtrapClient::initSendingEmails(
+        apiKey: $_ENV['MAILTRAP_API_KEY'], // Your API token from https://mailtrap.io/api-tokens
+        isBulk: true // Enable bulk sending
+    );
+
+    $baseEmail = (new MailtrapEmail())
+        ->from(new Address('[email protected]', 'Mailtrap Test')) // Use your domain installed in Mailtrap
+        ->subject('Batch Email Subject')
+        ->text('Batch email text')
+        ->html('<p>Batch email text</p>');
+
+    $recipientEmails = [
+        (new MailtrapEmail())->to(new Address('[email protected]', 'Recipient 1')),
+        (new MailtrapEmail())->to(new Address('[email protected]', 'Recipient 2')),
+    ];
+
+    $response = $mailtrap->batchSend($recipientEmails, $baseEmail);
+
+    var_dump(ResponseHelper::toArray($response)); // Output response body as array
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), "\n";
+}

examples/batch/bulk_template.php

@@ -0,0 +1,66 @@
+<?php
+
+use Mailtrap\Helper\ResponseHelper;
+use Mailtrap\MailtrapClient;
+use Mailtrap\Mime\MailtrapEmail;
+use Symfony\Component\Mime\Address;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * Email Batch Sending WITH TEMPLATE (Bulk)
+ *
+ * WARNING! If a template is provided, then subject, text, html, category and other params are forbidden.
+ *
+ * UUID of email template. Subject, text and html will be generated from template using optional template_variables.
+ * Optional template variables that will be used to generate actual subject, text and html from email template
+ *
+ * For this example, you need to have ready-to-use sending domain or, a Demo domain that allows sending emails to your own account email.
+ * @see https://help.mailtrap.io/article/69-sending-domain-setup
+ */
+try {
+     $mailtrap = MailtrapClient::initSendingEmails(
+        apiKey: $_ENV['MAILTRAP_API_KEY'], // Your API token from https://mailtrap.io/api-tokens
+        isBulk: true // Enable bulk sending
+    );
+
+    $baseEmail = (new MailtrapEmail())
+        ->from(new Address('[email protected]', 'Mailtrap Test')) // Use your domain installed in Mailtrap
+        ->templateUuid('bfa432fd-0000-0000-0000-8493da283a69') // Template UUID
+        ->templateVariables([
+            'user_name' => 'Jon Bush',
+            'next_step_link' => 'https://mailtrap.io/',
+            'get_started_link' => 'https://mailtrap.io/',
+            'company' => [
+                'name' => 'Best Company',
+                'address' => 'Its Address',
+            ],
+            'products' => [
+                [
+                    'name' => 'Product 1',
+                    'price' => 100,
+                ],
+                [
+                    'name' => 'Product 2',
+                    'price' => 200,
+                ],
+            ],
+        ]);
+
+    $recipientEmails = [
+        (new MailtrapEmail())
+            ->to(new Address('[email protected]', 'Recipient 1'))
+            // Optional: Override template variables for this recipient
+            ->templateVariables([
+                'user_name' => 'Custom User 1',
+            ]),
+        (new MailtrapEmail())
+            ->to(new Address('[email protected]', 'Recipient 2')),
+    ];
+
+    $response = $mailtrap->batchSend($recipientEmails, $baseEmail);
+
+    var_dump(ResponseHelper::toArray($response)); // Output response body as array
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), "\n";
+}

examples/batch/sandbox.php

@@ -0,0 +1,41 @@
+<?php
+
+use Mailtrap\Helper\ResponseHelper;
+use Mailtrap\MailtrapClient;
+use Mailtrap\Mime\MailtrapEmail;
+use Symfony\Component\Mime\Address;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * Test Email Batch
+ *
+ * Batch send email (text, html, text&html, templates).
+ * Please note that the endpoint will return a 200-level http status, even when sending for individual messages may fail.
+ * Users of this endpoint should check the success and errors for each message in the response (the results are ordered the same as the original messages - requests).
+ * Please note that the endpoint accepts up to 500 messages per API call, and up to 50 MB payload size, including attachments.
+ */
+try {
+    $mailtrap = MailtrapClient::initSendingEmails(
+        apiKey: $_ENV['MAILTRAP_API_KEY'], #your API token from here https://mailtrap.io/api-tokens
+        isSandbox: true, # Sandbox sending (@see https://help.mailtrap.io/article/109-getting-started-with-mailtrap-email-testing)
+        inboxId: $_ENV['MAILTRAP_INBOX_ID'] # required param for sandbox sending
+    );
+
+    $baseEmail = (new MailtrapEmail())
+        ->from(new Address('[email protected]', 'Mailtrap Test')) // Use your domain installed in Mailtrap
+        ->subject('Batch Email Subject')
+        ->text('Batch email text')
+        ->html('<p>Batch email text</p>');
+
+    $recipientEmails = [
+        (new MailtrapEmail())->to(new Address('[email protected]', 'Recipient 1')),
+        (new MailtrapEmail())->to(new Address('[email protected]', 'Recipient 2')),
+    ];
+
+    $response = $mailtrap->batchSend($recipientEmails, $baseEmail);
+
+    var_dump(ResponseHelper::toArray($response)); // Output response body as array
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), "\n";
+}

examples/batch/sandbox_template.php

@@ -0,0 +1,64 @@
+<?php
+
+use Mailtrap\Helper\ResponseHelper;
+use Mailtrap\MailtrapClient;
+use Mailtrap\Mime\MailtrapEmail;
+use Symfony\Component\Mime\Address;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * Test Email Batch WITH TEMPLATE
+ *
+ * WARNING! If a template is provided, then subject, text, html, category and other params are forbidden.
+ *
+ * UUID of email template. Subject, text and html will be generated from template using optional template_variables.
+ * Optional template variables that will be used to generate actual subject, text and html from email template
+ */
+try {
+    $mailtrap = MailtrapClient::initSendingEmails(
+        apiKey: $_ENV['MAILTRAP_API_KEY'], #your API token from here https://mailtrap.io/api-tokens
+        isSandbox: true, # Sandbox sending (@see https://help.mailtrap.io/article/109-getting-started-with-mailtrap-email-testing)
+        inboxId: $_ENV['MAILTRAP_INBOX_ID'] # required param for sandbox sending
+    );
+
+    $baseEmail = (new MailtrapEmail())
+        ->from(new Address('[email protected]', 'Mailtrap Test')) // Use your domain installed in Mailtrap
+        ->templateUuid('bfa432fd-0000-0000-0000-8493da283a69') // Template UUID
+        ->templateVariables([
+            'user_name' => 'Jon Bush',
+            'next_step_link' => 'https://mailtrap.io/',
+            'get_started_link' => 'https://mailtrap.io/',
+            'company' => [
+                'name' => 'Best Company',
+                'address' => 'Its Address',
+            ],
+            'products' => [
+                [
+                    'name' => 'Product 1',
+                    'price' => 100,
+                ],
+                [
+                    'name' => 'Product 2',
+                    'price' => 200,
+                ],
+            ],
+        ]);
+
+    $recipientEmails = [
+        (new MailtrapEmail())
+            ->to(new Address('[email protected]', 'Recipient 1'))
+            // Optional: Override template variables for this recipient
+            ->templateVariables([
+                'user_name' => 'Custom User 1',
+            ]),
+        (new MailtrapEmail())
+            ->to(new Address('[email protected]', 'Recipient 2')),
+    ];
+
+    $response = $mailtrap->batchSend($recipientEmails, $baseEmail);
+
+    var_dump(ResponseHelper::toArray($response)); // Output response body as array
+} catch (Exception $e) {
+    echo 'Caught exception: ', $e->getMessage(), "\n";
+}