gavroche/sitesearch

0.1.4 2016-07-26 18:19 UTC

README

Build Status StyleCI Scrutinizer Code Quality Code Coverage Code Climate Latest Stable Version Total Downloads License SensioLabsInsight Join the chat at https://gitter.im/gabrielbull/omnimail

Send email across all platforms using one interface.

Table Of Content

  1. Requirements
  2. Installation
  3. Providers
  4. Email
  5. Exceptions
  6. Logging
  7. License

Requirements

This library uses PHP 5.5+.

Installation

It is recommended that you install the Omnimail library through composer. To do so, run the Composer command to install the latest stable version of Omnimail library.

composer require omnimail/omnimail

Providers

AmazonSES

Installation

To use the AmazonSES sender class, you will need to install the daniel-zahariev/php-aws-ses library using composer.

composer require daniel-zahariev/php-aws-ses
Usage
use Omnimail\Email;
use Omnimail\AmazonSES;

$sender = new AmazonSES($accessKey, $secretKey);

$email = (new Email())
    ->addTo('example@email.com')
    ->setFrom('example@email.com')
    ->setSubject('Hello, world!')
    ->setTextBody('Hello World! How are you?');

$sender->send($email);

Mailgun

Installation

To use the Mailgun sender class, you will need to install the mailgun/mailgun-php library using composer. You do also need to install a HTTP client that sends messages. You can use any client that provided the virtual package php-http/client-implementation

composer require mailgun/mailgun-php php-http/guzzle6-adapter
Usage
use Omnimail\Email;
use Omnimail\Mailgun;

$sender = new Mailgun($apiKey, $domain);

$email = (new Email())
    ->addTo('example@email.com')
    ->setFrom('example@email.com')
    ->setSubject('Hello, world!')
    ->setTextBody('Hello World! How are you?');

$sender->send($email);

Mailjet

Installation

To use the Mailjet sender class, you will need to install the mailjet/mailjet-apiv3-php library using composer.

composer require mailjet/mailjet-apiv3-php
Usage
use Omnimail\Email;
use Omnimail\Mailjet;

$sender = new Mailjet($apikey, $apisecret);

$email = (new Email())
    ->addTo('example@email.com')
    ->setFrom('example@email.com')
    ->setSubject('Hello, world!')
    ->setTextBody('Hello World! How are you?');

$sender->send($email);

Mandrill

Installation

To use the Mandrill sender class, you will need to install the mandrill/mandrill library using composer.

composer require mandrill/mandrill
Usage
use Omnimail\Email;
use Omnimail\Mandrill;

$sender = new Mandrill($apiKey);

$email = (new Email())
    ->addTo('example@email.com')
    ->setFrom('example@email.com')
    ->setSubject('Hello, world!')
    ->setTextBody('Hello World! How are you?');

$sender->send($email);

Postmark

Installation

To use the Postmark sender class, you will need to install the wildbit/postmark-php library using composer.

composer require wildbit/postmark-php
Usage
use Omnimail\Email;
use Omnimail\Postmark;

$sender = new Postmark($serverApiToken);

$email = (new Email())
    ->addTo('example@email.com')
    ->setFrom('example@email.com')
    ->setSubject('Hello, world!')
    ->setTextBody('Hello World! How are you?');

$sender->send($email);

Sendgrid

Installation

To use the Sendgrid sender class, you will need to install the sendgrid/sendgrid library using composer.

composer require sendgrid/sendgrid
Usage
use Omnimail\Email;
use Omnimail\Sendgrid;

$sender = new Sendgrid($apiKey);

$email = (new Email())
    ->addTo('example@email.com')
    ->setFrom('example@email.com')
    ->setSubject('Hello, world!')
    ->setTextBody('Hello World! How are you?');

$sender->send($email);

SendinBlue

Installation

To use the SendinBlue sender class, you will need to install the mailin-api/mailin-api-php library using composer.

composer require mailin-api/mailin-api-php
Usage
use Omnimail\Email;
use Omnimail\SendinBlue;

$sender = new SendinBlue($accessKey);

$email = (new Email())
    ->addTo('example@email.com')
    ->setFrom('example@email.com')
    ->setSubject('Hello, world!')
    ->setTextBody('Hello World! How are you?');

$sender->send($email);

Email

An Email object implements the EmailInterface inteface. You can create your own Email class and send it to any sender if it implements the EmailInterface inteface.

To

The To property of the email is for defining the recipients of the email. You can set multiple recipients.

$email = new Email();
$email->addTo('recipent1@email.com', 'Recipient1 Name');
$email->addTo('recipent2@email.com', 'Recipient2 Name');

From

The From property of the email is for defining the sender of the email.

$email = new Email();
$email->setFrom('sender@email.com', 'Sender Name');

CC

Like the To property, the CC property can have multiple recipients.

$email = new Email();
$email->addCc('recipent1@email.com', 'Recipient1 Name');
$email->addCc('recipent2@email.com', 'Recipient2 Name');

BCC

Like the To property, the BCC property can have multiple recipients.

$email = new Email();
$email->addBcc('recipent1@email.com', 'Recipient1 Name');
$email->addBcc('recipent2@email.com', 'Recipient2 Name');

Reply To

The Reply To property of the email is for defining the email that should receive responses.

$email = new Email();
$email->setReplyTo('sender@email.com', 'Sender Name');

Subject

The Subject property of the email is for defining the subject of the email.

$email = new Email();
$email->setSubject('Hello, World!');

Text Body

The Text Body property of the email is for defining the text body of the email.

$email = new Email();
$email->setTextBody('This is plain text.');

HTML Body

The HTML Body property of the email is for defining the HTML body of the email.

$email = new Email();
$email->setHtmlBody('<h1>Hi!</h1><p>This is HTML!</p>');

Attachments

The Attachments property of the email is for joining attachments to the email.

Example using string as content
use Omnimail\Email;
use Omnimail\Attachment;

$attachment = new Attachment();
$attachment->setName('my_file.txt');
$attachment->setMimeType('text/plain');
$attachment->setContent('This is plain text');

$email = new Email();
$email->addAttachment($attachment);
Example using file path as content
use Omnimail\Email;
use Omnimail\Attachment;

$attachment = new Attachment();
$attachment->setMimeType('text/plain');
$attachment->setPath(__DIR__ . '/my_file.txt');

$email = new Email();
$email->addAttachment($attachment);

Inline attachments

use Omnimail\Email;
use Omnimail\Attachment;

$attachment = new Attachment();
$attachment->setPath(__DIR__ . '/image.png');
$attachment->setContentId('image.png');

$email = new Email();
$email->setHtmlBody('<p>Hello!</p><img src="cid:image.png">');
$email->addAttachment($attachment);

Exceptions

Failures to send emails will throw exceptions.

Exceptions

  • Omnimail\Exception\Exception
  • Omnimail\Exception\EmailDeliveryException
  • Omnimail\Exception\InvalidRequestException
  • Omnimail\Exception\UnauthorizedException

To catch all exception, consider the following.

try {
    $sender->send($email);
} catch (\Omnimail\Exception\Exception $e) {
    echo 'Something went wrong: ' . $e->getMessage();
}

To catch specific exceptions, consider the following.

try {
    $sender->send($email);
} catch (\Omnimail\Exception\UnauthorizedException $e) {
    echo 'Your credentials must be incorrect';
} catch (\Omnimail\Exception\InvalidRequestException $e) {
    echo 'The request is badly formatted, check that all required fields are filled.';
} catch (\Omnimail\Exception\EmailDeliveryException $e) {
    echo 'The email did not go out.';
}

Logging

All sender constructors take a PSR-3 compatible logger.

Email sent (including the email) are logged at INFO level. Errors (including the email) are reported at the ERROR level.

Example using Monolog

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Omnimail\Mailgun;

$logger = new Logger('name');
$logger->pushHandler(new StreamHandler('path/to/your.log', Logger::INFO));

$sender = new Mailgun($apiKey, $domain, $logger);
$sender->send($email);

License

Omnimail is licensed under The MIT License (MIT).