README

mailer-sdk is a PHP SDK for the mailer API

Getting started

Installing

You can install via Composer:

composer require milosp/mailer-sdk

or include the SDK under repositories in your composer.json file:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/miilos/mailer-sdk"
    }
]

Usage

The Mailer class allows you to send emails by calling the API, or by dispatching messages into a RabbitMQ exchange, which the API will then also pick up. First, configure the Mailer:

Configuration

The mailer takes in an $options array as an argument with the following keys:

• base_uri - the base URL where the API is located (like http://localhost:8000)
• api_client - the HTTP client to use when communicating with the API
• amqp_client - the AMQP client to use when dispatching messages

HTTP client configuration

By default, the SDK uses the Symfony HTTP client to make requests. If you have symfony/http-client installed, you don't need to do any configuration. If you want to use a different HTTP client (Guzzle, cURL...), just create an instance of the ApiClient class provided by the SDK. The ApiClient class uses PSR compliant interfaces to make it possible to integrate whatever http client you want to use. To create an instance of ApiClient, pass in the following arguments:

use Milos\MailerSdk\Core\ApiClient;

$apiClient = new ApiClient(
    $httpClient,
    $requestFactory,
    $streamFactory
);

• $httpClient - an instance of the PSR-18 ClientInterface, handles PSR-7 requests and responses
• $requestFactory - an instance of the PSR-17 RequestFactoryInterface, handles PSR-7 request creation
• $streamFactory - an instance of the PSR-17 StreamFactoryInterface, handles creating streams when sending requests with data in their bodies

pass the object to the Mailer constructor:

$mailer = new Mailer([
    'base_uri' => 'http://example.com:8000'
    'api_client' => $apiClient
]);

AMQP client configuration

If you don't plan on dispatching messages into the API's queue, you don't need to pass in anything under the amqp_client key in the config. If you do want to dispatch messages, pass in an instance of the AmqpClient class:

use Milos\MailerSdk\Core\AmqpClient;

$amqpClient = new AmqpClient(
    $host, // 'localhost'
    $port, // 5674
    $user, // 'guest'
    $password, // 'guest'
    $exchange, // 'your-exchange'
    $routingKey // 'your-routing-key'
);

and pass the object in the $options:

$mailer = new Mailer([
    'base_uri' => 'http://example.com:8000'
    'amqp_client' => $amqpClient
]);

The $exchange and $routingKey parameters are optional and should be passed to the constructor if you only plan to dispatch messages into the same exchange and queue every time. If those might change, pass the $exchange and $routingKey into the sendAsMessage() method to configure these parameters on a per-message basis. If you use both the constructor and the method parameters, the parameters passed to sendAsMessage() take precedence.

Sending emails through the API

In order to send emails through the API, first assemble an EmailDto object. You can use the EmailBuilder class for this:

use Milos\MailerSdk\Dtos\EmailBuilder;

$emailDto = (new EmailBuilder())
    ->setSubject('test')
    ->setFrom('testSender@gmail.com')
    ->setTo([
        'testRecipient@gmail.com'
    ])
    ->setCc([
        'testCCAddress@gmail.com
    ])
    ->setBcc([
        'testBCCAddress@gmail.com
    ])
    ->setBody('This a test email body')
    ->getEmail();

and then send the email:

$mailer->emails->send($emailDto);

The send() method returns the API's response as an instance of ResponseInterface.

You can also validate the email before getting the object to make sure you have the essential properties (subject, from, to and body) set:

use Milos\MailerSdk\Dtos\EmailBuilder;

$emailDto = (new EmailBuilder())
    ->setSubject('test')
    ->setFrom('testSender@gmail.com')
    ->setTo([
        'testRecipient@gmail.com'
    ])
    ->validate() // throws a MailerException - body isn't set
    ->getEmail();

You can also set API-specific things like an email template, body template or variables:

use Milos\MailerSdk\Dtos\EmailBuilder;

$emailDto = (new EmailBuilder())
    ->setSubject('test')
    ->setFrom('testSender@gmail.com')
    ->setTo([
        'testRecipient@gmail.com'
    ])
    ->setBodyTemplate('test-body-template')
    ->validate() // this passes validation - a template is used for the body
    ->getEmail();

use Milos\MailerSdk\Dtos\EmailBuilder;

$emailDto = (new EmailBuilder())
    ->setSubject('test')
    ->setFrom('testSender@gmail.com')
    ->setTo([
        'testRecipient@gmail.com'
    ])
    ->setBody('<h1>This template uses variables: {{ var }}</h1>')
    ->setVariables([
        'var' => 'some variable value'
    ])
    ->getEmail();

If you have an email template set up that fills in all the fields of an email, you can also do this:

use Milos\MailerSdk\Dtos\EmailBuilder;

$emailDto = (new EmailBuilder())
    ->setEmailTemplate('some-email-template')
    ->getEmail();

You can also override specific fields of a template:

use Milos\MailerSdk\Dtos\EmailBuilder;

$emailDto = (new EmailBuilder())
    ->setSubject('New subject') // this will override the template's subject
    ->setEmailTemplate('some-email-template')
    ->getEmail();

Sending emails by dispatching RabbitMQ messages

To do this, you must set up an AmqpClient, otherwise, a MailerException will be thrown when you try to dispatch a message.

When sending an email this way, you also create an EmailDto object, you just use a different method to send the email - sendAsMessage():

use Milos\MailerSdk\Dtos\EmailBuilder;

$emailDto = (new EmailBuilder())
    ->...
    
$mailer->emails->sendAsMessage($emailDto)

You can specify an exchange and routing key for the message here:

use Milos\MailerSdk\Dtos\EmailBuilder;

$emailDto = (new EmailBuilder())
    ->...
    
$mailer->emails->sendAsMessage($emailDto, 'your-exchange', 'your-routing-key')

Authors

• Miloš Popović