diff --git a/CHANGELOG.md b/CHANGELOG.md index 8ddfab7..62773f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +## [3.9.1] - 2025-10-27 +- Improve README + ## [3.9.0] - 2025-10-14 - Add Contact Export functionality diff --git a/README.md b/README.md index 50cdcfe..6abe613 100644 --- a/README.md +++ b/README.md @@ -13,35 +13,6 @@ To get the most of this official Mailtrap.io PHP SDK: - [Create a Mailtrap account](https://mailtrap.io/signup) - [Verify your domain](https://mailtrap.io/sending/domains) -## Supported functionality - -It supports Symphony and Laravel integrations. - -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 - - ## Installation You can install the package via [composer](http://getcomposer.org/) @@ -59,10 +30,100 @@ composer require railsware/mailtrap-php symfony/http-client nyholm/psr7 composer require railsware/mailtrap-php guzzlehttp/guzzle php-http/guzzle7-adapter ``` +## Framework integration +If you use a framework, install a bridge package for seamless configuration: + +* [Symfony](src/Bridge/Symfony) +* [Laravel](src/Bridge/Laravel) + +These provide service registration and allow you to inject the client where needed with minimal manual bootstrapping. + ## Usage You should use Composer autoloader in your application to automatically load your dependencies. -Here's how to send a message using the SDK: +### Minimal usage (Transactional sending) +The quickest way to send a single transactional email with only the required parameters: + +```php +from(new Address('sender@example.com')) + ->to(new Address('recipient@example.com')) + ->subject('Hello from Mailtrap PHP') + ->text('Plain text body'); + +$response = $mailtrap->send($email); + +// Access response body as array (helper optional) +var_dump(ResponseHelper::toArray($response)); +``` + +### Sandbox vs Production (easy switching) +Mailtrap lets you test safely in the Email Sandbox and then switch to Production (Sending) with one flag. + +Example `.env` variables (or export in shell): +``` +MAILTRAP_API_KEY=your_api_token # https://mailtrap.io/api-tokens +MAILTRAP_USE_SANDBOX=true # true/false toggle +MAILTRAP_INBOX_ID=123456 # Only needed for sandbox +``` + +Bootstrap logic: +```php +from(new Address($isSandbox ? 'sandbox@example.com' : 'no-reply@your-domain.com')) + ->to(new Address('recipient@example.com')) + ->subject($isSandbox ? '[SANDBOX] Demo email' : 'Welcome onboard') + ->text('This is a minimal body for demonstration purposes.'); + +$response = $client->send($email); + +// Access response body as array (helper optional) +var_dump(ResponseHelper::toArray($response)); +``` + +Bulk stream example (optional) differs only by setting `isBulk: true`: +```php +$bulkClient = MailtrapClient::initSendingEmails(apiKey: $apiKey, isBulk: true); +``` + +Recommendations: +- Toggle sandbox with `MAILTRAP_USE_SANDBOX`. +- Use separate API tokens for Production and Sandbox. +- Keep initialisation in a single factory object/service so that switching is centralised. + +### Full-featured usage example ```php addCc('staging@example.com') ->bcc('mailtrapdev@example.com') ->subject('Best practices of building HTML emails') - ->text('Hey! Learn the best practices of building HTML emails and play with ready-to-go templates. Mailtrap's Guide on How to Build HTML Email is live on our blog') + ->text('Hey! Learn the best practices of building HTML emails and play with ready-to-go templates. Mailtrap\'s Guide on How to Build HTML Email is live on our blog') ->html( '


Hey
Learn the best practices of building HTML emails and play with ready-to-go templates.

-

Mailtrap's Guide on How to Build HTML Email is live on our blog

+

Mailtrap\'s Guide on How to Build HTML Email is live on our blog

' @@ -124,35 +188,44 @@ try { } -// OR -> Mailtrap BULK SENDING client (real) -try { - $mailtrapBulkSending = MailtrapClient::initSendingEmails( - apiKey: getenv('MAILTRAP_API_KEY'), # your API token from here https://mailtrap.io/api-tokens - isBulk: true # Bulk sending (@see https://help.mailtrap.io/article/113-sending-streams) - ); +// OR Template email sending - $response = $mailtrapBulkSending->send($email); - - var_dump(ResponseHelper::toArray($response)); // body (array) -} catch (Exception $e) { - echo 'Caught exception: ', $e->getMessage(), "\n"; -} +$email = (new MailtrapEmail()) + ->from(new Address('example@your-domain-here.com', 'Mailtrap Test')) + ->replyTo(new Address('reply@your-domain-here.com')) + ->to(new Address('example@gmail.com', 'Jon')) + ->templateUuid('bfa432fd-0000-0000-0000-8493da283a69') + ->templateVariables([ + 'user_name' => 'Jon Bush', + 'next_step_link' => 'https://mailtrap.io/', + 'get_started_link' => 'https://mailtrap.io/', + 'onboarding_video_link' => 'some_video_link', + 'company' => [ + 'name' => 'Best Company', + 'address' => 'Its Address', + ], + 'products' => [ + [ + 'name' => 'Product 1', + 'price' => 100, + ], + [ + 'name' => 'Product 2', + 'price' => 200, + ], + ], + 'isBool' => true, + 'int' => 123 + ]) +; -// OR -> Mailtrap Testing client (sandbox) try { - $mailtrapTesting = MailtrapClient::initSendingEmails( - apiKey: getenv('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: getenv('MAILTRAP_INBOX_ID') # required param for sandbox sending - ); - - $response = $mailtrapTesting->send($email); + $response = $mailtrap->send($email); var_dump(ResponseHelper::toArray($response)); // body (array) } catch (Exception $e) { echo 'Caught exception: ', $e->getMessage(), "\n"; } - ``` ### All usage examples @@ -162,13 +235,31 @@ You can find more examples [here](examples). * [Testing examples](examples/testing) * [Sending examples](examples/sending) +## Supported functionality -## Framework integration - -If you are using a framework you might consider these composer packages to make the framework integration easier. - -* [Symfony](src/Bridge/Symfony) -* [Laravel](src/Bridge/Laravel) +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 ## Contributing