Skip to content

Improve README #54

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 28, 2025
Merged

Improve README #54

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
96afc32
improve readme file
gaalferov Oct 20, 2025
09d8185
remove strict_types
gaalferov Oct 20, 2025
143a0f4
remove strict_types 2
gaalferov Oct 20, 2025
15287c1
update changelog for README improvements
gaalferov Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 152 additions & 61 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/)

Expand All @@ -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
<?php

use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapClient;
use Mailtrap\Mime\MailtrapEmail;
use Symfony\Component\Mime\Address;

require __DIR__ . '/vendor/autoload.php';

$mailtrap = MailtrapClient::initSendingEmails(
apiKey: getenv('MAILTRAP_API_KEY') // your API key here https://mailtrap.io/api-tokens
);

$email = (new MailtrapEmail())
->from(new Address('[email protected]'))
->to(new Address('[email protected]'))
->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
<?php

use Mailtrap\Helper\ResponseHelper;
use Mailtrap\MailtrapClient;
use Mailtrap\Mime\MailtrapEmail;
use Symfony\Component\Mime\Address;

require __DIR__ . '/vendor/autoload.php';

$apiKey = getenv('MAILTRAP_API_KEY');
$isSandbox = filter_var(getenv('MAILTRAP_USE_SANDBOX'), FILTER_VALIDATE_BOOL);
$inboxId = $isSandbox ? getenv('MAILTRAP_INBOX_ID') : null; // required only for sandbox

$client = MailtrapClient::initSendingEmails(
apiKey: $apiKey,
isSandbox: $isSandbox,
inboxId: $inboxId // null is ignored for production
);

$email = (new MailtrapEmail())
->from(new Address($isSandbox ? '[email protected]' : '[email protected]'))
->to(new Address('[email protected]'))
->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
<?php
Expand All @@ -76,9 +137,12 @@ use Symfony\Component\Mime\Header\UnstructuredHeader;

require __DIR__ . '/vendor/autoload.php';

// Mailtrap SENDING client (real) for transactional emails
// Init Mailtrap client depending on your needs
$mailtrap = MailtrapClient::initSendingEmails(
apiKey: getenv('MAILTRAP_API_KEY') # your API token from here https://mailtrap.io/api-tokens
apiKey: getenv('MAILTRAP_API_KEY'), # your API token
isBulk: false, # set to true for bulk email sending (false by default)
isSandbox: false, # set to true for sandbox mode (false by default)
inboxId: null # optional, only for sandbox mode (false by default)
);

$email = (new MailtrapEmail())
Expand All @@ -90,13 +154,13 @@ $email = (new MailtrapEmail())
->addCc('[email protected]')
->bcc('[email protected]')
->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(
'<html>
<body>
<p><br>Hey</br>
Learn the best practices of building HTML emails and play with ready-to-go templates.</p>
<p><a href="https://mailtrap.io/blog/build-html-email/">Mailtrap's Guide on How to Build HTML Email</a> is live on our blog</p>
<p><a href="https://mailtrap.io/blog/build-html-email/">Mailtrap\'s Guide on How to Build HTML Email</a> is live on our blog</p>
<img src="cid:logo">
</body>
</html>'
Expand Down Expand Up @@ -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('[email protected]', 'Mailtrap Test'))
->replyTo(new Address('[email protected]'))
->to(new Address('[email protected]', '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
Expand All @@ -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

Expand Down