abishekrsrikaanth/mailto

Laravel 4 Package to integrate with multiple Cloud Email Providers

1.2 2014-06-11 03:38 UTC

Requires

• php: >=5.3.0
• guzzle/guzzle: 3.8.*@dev
• illuminate/support: 4.x

BSD-3-Clause

• Abishek R Srikaanth

• email
• laravel
• mandrill
• laravel-4

README

####Email Providers Supported

• Installation
• Mandrill - (Documentation)
  • Sending Email using Mandrill
  • Queuing Email using Mandrill
  • Sending Email at a given Time
  • Sending Email to a Batch of recipients
  • Sending Email to a Batch of recipients at a given time
  • Passing the credentials dynamically for Mandrill
  • Managing Webhooks
  • Methods
• PostmarkApp
  • Sending Email using PostMark
  • Sending Batch Emails using PostMark

###Installation Add abishekrsrikaanth/mailto as a requirement to composer.json:

{
    ...
    "require": {
        ...
        "abishekrsrikaanth/mailto": "1.*"
        ...
    },
}

Update composer:

$ php composer.phar update

Add the provider to your app/config/app.php:

'providers' => array(
    ...
    'Abishekrsrikaanth\Mailto\MailtoServiceProvider',
),

and the Facade info on app/config/app.php

'aliases'   => array(
    ...
	'MailTo'      => 'Abishekrsrikaanth\Mailto\Facades\Mailto',
),

Publish the Configuration and setup the config with the credentials of the different email providers

php artisan config:publish abishekrsrikaanth/mailto

###Mandrill #####Sending Email using Mandrill

$mandrill = MailTo::Mandrill();
$mandrill->addRecipient($email, $name)
         ->setFrom($email, $name)
         ->setHtml($html)
         ->setText($text)
         ->setSubject($subject)
         ->send();

#####Queuing Email using Mandrill

$mandrill = MailTo::Mandrill();
$mandrill->addRecipient($email, $name)
         ->setFrom($email, $name)
         ->setHtml($html)
         ->setText($text)
         ->setSubject($subject)
         ->queue();

#####Sending Email at a given Time

$timestamp = new DateTime('+1 hour');

$mandrill = MailTo::Mandrill();
$mandrill->addRecipient($email, $name)
         ->setFrom($email, $name)
         ->setHtml($html)
         ->setText($text)
         ->setSubject($subject)
         ->send($timestamp);

#####Sending Email to a Batch of recipients

$mandrill = MailTo::Mandrill();
$mandrill->addRecipient($email, $name)
         ->setFrom($email, $name)
         ->setHtml($html)
         ->setText($text)
         ->setSubject($subject)
         ->sendBatch();

#####Sending Email to a Batch of recipients at a given time

$timestamp = new DateTime('+1 hour');

$mandrill = MailTo::Mandrill();
$mandrill->addRecipient($email, $name)
         ->setFrom($email, $name)
         ->setHtml($html)
         ->setText($text)
         ->setSubject($subject)
         ->sendBatch($timestamp);

#####Passing the credentials dynamically for Mandrill

$mandrill = MailTo::Mandrill(array('apikey'=>'MADRILL_API_KEY'));
$mandrill->addRecipient($email, $name)
         ->setFrom($email, $name)
         ->setHtml($html)
         ->setText($text)
         ->setSubject($subject)
         ->send();

#####Example Response from Mandrill - Success

[
    {
        "email": "[e-mail]",
        "status": "sent",
        "reject_reason": "hard-bounce",
        "_id": "abc123abc123abc123abc123abc123"
    }
]

#####Example Response from Mandrill - Error

{
    "status": "error",
    "code": 10,
    "name": "PaymentRequired",
    "message": "This feature is only available for accounts with a positive balance."
}

#####Managing Webhooks The configuration of this package allows you to configure the webhooks that have been created on the mandrill control panel. When enabled and configured, the necessary routes for the web hooks are automatically created and is ready to implement. The details of enabling and configuring the web hooks are mentioned below.

'mandrill' => array(
		'apikey'    => 'MANDRILL_API_TOKEN',
		'web_hooks' => array(
			'enabled' => false,
			'routes'  => array(
				array(
					'route_url'   => '/mandrill/send',
					'route_types' => array('send'),
					'webhook_key' => 'API_WEBHOOK_KEY',
					'listener'    => array(
						'type' => 'event',
						'name' => ''
					),
					'verify_hook' => false
				),
				array(
					'route_url'   => '/mandrill/bounce',
					'route_types' => array(''),
					'webhook_key' => '',
					'listener'    => array(
						'type' => 'queue',
						'name' => ''
					),
					'verify_hook' => false
				)
			)
		)
	)

web_hooks.enabled

Indicates whether to enable or disable the configuration of web hooks

web_hooks.routes

An array of route configurations that you wish to define for various event types of mandrill

Lets look at detail the route configurations.

routes.route_url

The route URL of the webhook. On the example above it is configured as /mandrill/send, the route will be configured to http://base_url/mandrill/send

routes.route_types

An array object that contains the list of events that have been configured for this web hook. You would have done this when setting up the web hook on the Mandrill Control Panel. The different event types are listed on http://help.mandrill.com/entries/21738186-Introduction-to-Webhooks. This configuration will only be used if verify_hook is set to true

routes.webhook_key

A key that is automatically generated when a webhook is created. This can be found on the Webhook Control panel of mandrill. Every Webhook has a different key generated. Again, this configuration will only be used if verify_hook is set to true

routes.listener

The listener is used to configure a hook on the application to listen to when the webhook is called. There are 2 listeners that you can configure. Event, Queue. The type takes the type of listener that you want to configure it to [event, queue]. The name takes the name of the listener that should be called. A look at the Laravel docs on how to setup an Event Listener or Queue will help understand.

routes.verify_hook

It takes a boolean value and notifies the route to verify the web hook call. There are 2 verfications that are done here
a. Mandrill sends an encrypted signature based on the data and the key of the webhook that can be used to verify if the web hook call is actually coming from Mandrill.
b. It checks if the event type matches the web_hook call.

Setting the configuration to true will automatically start validating the web hook calls if the calls are from Mandrill or not. No additional coding required

#####Methods

###PostMarkApp

#####Sending Email

$postMark = MailTo::PostMark();
$message  = $postMark->getMessageInstance();
$message->addRecipient("RECIPIENT_EMAIL")
	->setFrom("FROM_EMAIL", "FROM_NAME")
	->setSubject("EMAIL_SUBJECT")
	->setHtml("HTML_CONTENT_GOES_HERE")
	->setText("TEXT_CONTENT_GOES_HERE");
$postMark->send($message);

#####Example Response from Postmark for Send Method if Message sent successfully

{
  "ErrorCode" : 0,
  "Message" : "OK",
  "MessageID" : "b7bc2f4a-e38e-4336-af7d-e6c392c2f817",
  "SubmittedAt" : "2010-11-26T12:01:05.1794748-05:00",
  "To" : "[e-mail]"
}

#####Sending Batch Email

$postMark = MailTo::PostMark();
$message  = $postMark->getMessageInstance();
$message->addRecipient("RECIPIENT_EMAIL")
    ->setFrom("FROM_EMAIL", "FROM_NAME")
	->setSubject("EMAIL_SUBJECT")
	->setHtml("HTML_CONTENT_GOES_HERE")
	->setText("TEXT_CONTENT_GOES_HERE");
$postMark->send($message);

#####Example Response from Postmark for Send Method if Message sent successfully

[
    {
      "ErrorCode" : 0,
      "Message" : "OK",
      "MessageID" : "b7bc2f4a-e38e-4336-af7d-e6c392c2f817",
      "SubmittedAt" : "2010-11-26T12:01:05.1794748-05:00",
      "To" : "[e-mail]"
    },
    {
      "ErrorCode" : 0,
      "Message" : "OK",
      "MessageID" : "e2ecbbfc-fe12-463d-b933-9fe22915106d",
      "SubmittedAt" : "2010-11-26T12:01:05.1794748-05:00",
      "To" : "[e-mail]"
    }
]

#####Work in progress

• ElasticMail

#####Implementations coming soon

• MailGun

• PostageApp

• Mad Mimi

• Alpha Mail