Added Mailgun email validation service

Updated docs
Added public apikey to config
Closes #12

README.md

@@ -27,6 +27,7 @@ It's main advantage is that the syntax is the same as the Laravel Mail component
 	- [Testmode](#testmode)
 	- [Catch all](#catch-all)
 	- [Custom Data](#custom-data)
+	- [Email Validation](#email-validation)
 
 ## Installation ##
 
@@ -397,5 +398,120 @@ Mailgun::send('emails.welcome', $data, function($message)
 });
 ```
 
+### Email Validation ###
+Mailgun offers an email validation service which checks an email address on the following:
+* Syntax checks (RFC defined grammar)
+* DNS validation
+* Spell checks
+* Email Service Provider (ESP) specific local-part grammar (if available).
+
+#### Single address ####
+Validation a single address:
+
+```php
+Mailgun::validate("[email protected]")
+```
+
+The `validate` method returns the following object:
+```php
+stdClass Object
+(
+    [address] => [email protected]
+    [did_you_mean] => 
+    [is_valid] => 1
+    [parts] => stdClass Object
+        (
+            [display_name] => 
+            [domain] => bar.com
+            [local_part] => foo
+        )
+
+)
+```
+
+It will also try to correct typo's:
+```php
+Mailgun::validate("[email protected]")
+```
+returns:
+```php
+stdClass Object
+(
+    [address] => [email protected]
+    [did_you_mean] => [email protected]
+    [is_valid] => 1
+    [parts] => stdClass Object
+        (
+            [display_name] => 
+            [domain] => gmil.com
+            [local_part] => foo
+        )
+
+)
+```
+#### Multiple addresses ####
+To validate multiple addresses you can use the `parse` method.
+
+This parses a delimiter separated list of email addresses into two lists: parsed addresses and unparsable portions. The parsed addresses are a list of addresses that are syntactically valid (and optionally have DNS and ESP specific grammar checks) the unparsable list is a list of characters sequences that the parser was not able to understand. These often align with invalid email addresses, but not always. Delimiter characters are comma (,) and semicolon (;).
+
+The `parse` method accepts two arguments:
+* `addresses`: An array of addresses **or** a delimiter separated string of addresses
+* `syntaxOnly`: Perform only syntax checks or DNS and ESP specific validation as well. (true by default)
+
+**Syntax only validation:**
+```php
+$addresses = 'Alice <alice@example.com>,[email protected],example.com';
+//or
+$addresses = array(
+	'Alice <alice@example.com>',
+	'[email protected]',
+	'example.com'
+);
+
+Mailgun::parse($addresses);
+```
+returns:
+```php
+stdClass Object
+(
+    [parsed] => Array
+        (
+            [0] => Alice <alice@example.com>
+            [1] => [email protected]
+        )
+
+    [unparseable] => Array
+        (
+            [0] => example.com
+        )
+
+)
+```
+
+**Validation including DNS and ESP validation:**
+```php
+$addresses = 'Alice <alice@example.com>,[email protected],example.com';
+Mailgun::parse($addresses, false);
+```
+returns:
+```php
+stdClass Object
+(
+    [parsed] => Array
+        (
+        )
+
+    [unparseable] => Array
+        (
+            [0] => Alice <alice@example.com>
+            [1] => [email protected]
+            [2] => example.com
+        )
+
+)
+```
+
+
+
 <br />
 [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/Bogardo/mailgun/trend.png)](https://bitdeli.com/free "Bitdeli Badge")

src/Bogardo/Mailgun/Mailgun.php

@@ -47,7 +47,8 @@ class Mailgun
 	 * Create a new Mailer instance.
 	 *
 	 * @param  \Illuminate\View\Environment $views
-	 * @return void
+	 *
+	 * @return \Bogardo\Mailgun\Mailgun
 	 */
 	public function __construct(Environment $views)
 	{
@@ -70,8 +71,6 @@ protected function _init()
 	/**
 	 * Set the global from address and name.
 	 *
-	 * @param  string $address
-	 * @param  string $name
 	 * @return void
 	 */
 	protected function alwaysFrom()
@@ -84,9 +83,11 @@ protected function alwaysFrom()
 	/**
 	 * Send a new message
 	 *
-	 * @param  string|array $view
-	 * @param  array $data
+	 * @param  string|array   $view
+	 * @param  array          $data
 	 * @param  Closure|string $callback
+	 * @param bool            $mustInit
+	 *
 	 * @return object Mailgun response containing http_response_body and http_response_code
 	 */
 	public function send($view, array $data, $callback, $mustInit = true)
@@ -100,13 +101,51 @@ public function send($view, array $data, $callback, $mustInit = true)
 		return $this->mailgun->sendMessage(Config::get('mailgun::domain'), $this->getMessageData(), $this->getAttachmentData());
 	}
 
+	/**
+	 * @param $address
+	 *
+	 * @return mixed
+	 */
+	public function validate($address)
+	{
+		$this->mailgun = new Mg(Config::get('mailgun::public_api_key'));
+
+		$data = $this->mailgun->get("address/validate", array('address' => $address));
+		return $data->http_response_body;
+	}
+
+	/**
+	 * @param      $addresses
+	 * @param bool $syntaxOnly
+	 *
+	 * @return mixed
+	 */
+	public function parse($addresses, $syntaxOnly = true)
+	{
+		$this->mailgun = new Mg(Config::get('mailgun::public_api_key'));
+
+		if (is_array($addresses)) {
+			$addresses = implode(',', $addresses);
+		}
+
+		if ($syntaxOnly === true) {
+			$syntaxOnly = 'true';
+		} else {
+			$syntaxOnly = 'false';
+		}
+
+		$data = $this->mailgun->get("address/parse", array('addresses' => $addresses, 'syntax_only' => $syntaxOnly));
+		return $data->http_response_body;
+	}
+
 	/**
 	 * Queue a new e-mail message for sending after (n) seconds/minutes/hours/days.
 	 *
-	 * @param  int|string|array $delay
-	 * @param  string|array $view
-	 * @param  array $data
-	 * @param  Closure|string $callback
+	 * @param  int|string|array $time
+	 * @param  string|array     $view
+	 * @param  array            $data
+	 * @param  Closure|string   $callback
+	 *
 	 * @return object Mailgun response containing http_response_body and http_response_code
 	 */
 	public function later($time, $view, array $data, $callback)
@@ -167,7 +206,7 @@ protected function getTextMessage($view, $data)
 
 	/**
 	 * Get message data
-	 * @return array \Bogardo\Mailgun\Mailgun\Message object casted to array
+	 * @return array Message object casted to array
 	 */
 	protected function getMessageData()
 	{

src/config/config.php

@@ -1,4 +1,4 @@
-<?php 
+<?php
 
 return array(
 
@@ -22,26 +22,31 @@
 
 
 	/**
-	 * Mailgun API key (non-public)
+	 * Mailgun (private) API key
 	 *
 	 */
 	'api_key' => '',
 
+	/**
+	 * Mailgun public API key
+	 *
+	 */
+	'public_api_key' => '',
 
 	/**
 	 * Domain name registered with Mailgun
 	 *
 	 */
 	'domain' => '',
-	
+
 	/**
 	 * Force the from address
 	 *
 	 * When your `from` e-mail address is not from the domain specified some
 	 * e-mail clients (Outlook) tend to display the from address incorrectly
 	 * By enabling this setting Mailgun will force the `from` address so the
 	 * from address will be displayed correctly in all e-mail clients.
-	 * 
+	 *
 	 * Warning:
 	 * This parameter is not documented in the Mailgun documentation
 	 * because if enabled, Mailgun is not able to handle soft bounces