diff --git a/README.md b/README.md index a766002..08bb513 100644 --- a/README.md +++ b/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("foo@bar.com") +``` + +The `validate` method returns the following object: +```php +stdClass Object +( + [address] => foo@bar.com + [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("foo@gmil.com") +``` +returns: +```php +stdClass Object +( + [address] => foo@gmil.com + [did_you_mean] => foo@gmail.com + [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 ,bob@example.com,example.com'; +//or +$addresses = array( + 'Alice ', + 'bob@example.com', + 'example.com' +); + +Mailgun::parse($addresses); +``` +returns: +```php +stdClass Object +( + [parsed] => Array + ( + [0] => Alice + [1] => bob@example.com + ) + + [unparseable] => Array + ( + [0] => example.com + ) + +) +``` + +**Validation including DNS and ESP validation:** +```php +$addresses = 'Alice ,bob@example.com,example.com'; +Mailgun::parse($addresses, false); +``` +returns: +```php +stdClass Object +( + [parsed] => Array + ( + ) + + [unparseable] => Array + ( + [0] => Alice + [1] => bob@example.com + [2] => example.com + ) + +) +``` + + +
[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/Bogardo/mailgun/trend.png)](https://bitdeli.com/free "Bitdeli Badge") diff --git a/src/Bogardo/Mailgun/Mailgun.php b/src/Bogardo/Mailgun/Mailgun.php index c663d9b..5cb6fad 100644 --- a/src/Bogardo/Mailgun/Mailgun.php +++ b/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() { diff --git a/src/config/config.php b/src/config/config.php index 6378343..98f1929 100644 --- a/src/config/config.php +++ b/src/config/config.php @@ -1,4 +1,4 @@ - '', + /** + * Mailgun public API key + * + */ + 'public_api_key' => '', /** * Domain name registered with Mailgun * */ 'domain' => '', - + /** * Force the from address * @@ -41,7 +46,7 @@ * 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