Mailgun - Lists
====================
This is the Mailgun PHP *Lists* utilities.
The below assumes you've already installed the Mailgun PHP SDK in to your project. If not, go back to the master README for instructions.
There is currently one utility provided.
OptInHandler: Provides methods for authenticating an OptInRequest.
The typical flow for using this utility would be as follow:
(Customer Requests Subscribe) -> [Generate Opt In Link] -> [Email Customer Opt In Link]
(Customer Clicks Opt In Link) -> [Validate Opt In Link] -> [Subscribe User] -> [Send final confirmation]
The above flow is modeled below.
Usage - Opt-In Handler (Customer Requests Subscribe)
----------------------------------------------------
Here's how to use Opt-In Handler to validate Opt-In requests.
```php
# First, instantiate the SDK with your API credentials and domain.
$mg = new Mailgun("key-example");
$domain = "example.com";
# Next, instantiate an OptInHandler object from the SDK.
$optInHandler = $mg->OptInHandler();
$ Next, generate a hash.
$mailingList = 'youlist@example.com';
$secretPassphrase = 'a_secret_passphrase';
$recipientAddress = 'recipient@example.com'
$generatedHash = $optInHandler->generateHash($mailingList, $secretPassphrase, $recipientAddress);
# Now, let's send a confirmation to the recipient.
$mg->sendMessage($domain, array('from' => 'bob@example.com',
'to' => 'sally@example.com',
'subject' => 'Please Confirm!',
'html' => 'Hello,
You have requested to be subscribed to the mailing list {$mailingList}.
Please confirm your subscription.
Thank you!'));
$ Finally, let's add the subscriber to a Mailing List, as unsubscribed, so we can track non-conversions.
$mg->post('{$domain}/lists/{$mailingList}', array('address' => $recipientAddress,
'subscribed' => 'no',
'upsert' => 'yes');
```
Usage - Opt-In Handler (Customer Clicks Opt In Link)
----------------------------------------------------
Here's how to use Opt-In Handler to validate an Opt-In Hash.
```php
# First, instantiate the SDK with your API credentials and domain.
$mg = new Mailgun("key-example");
$domain = "example.com";
# Next, instantiate an OptInHandler object from the SDK.
$optInHandler = $mg->OptInHandler();
$ Next, grab the hash.
$inboundHash = $_GET['hash'];
$secretPassphrase = 'a_secret_passphrase';
# Now, validate the captured hash.
$hashValidation = $optInHandler->validateHash($secretPassphrase, $inboundHash);
# Lastly, check to see if we have results, parse, subscribe, and send confirmation.
if($hashValidation){
$validatedList = $hashValidation['mailingList'];
$validatedRecipient = $hashValidation['recipientAddress'];
$mg->put('{$domain}/lists/{$validatedList}/{$validatedRecipient}',
array('address' => $recipientAddress,
'subscribed' => 'yes');
$mg->sendMessage($domain, array('from' => 'bob@example.com',
'to' => 'sally@example.com',
'subject' => 'Please Confirm!',
'html' => 'Hello,
We've successfully subscribed you to the list, {$mailingList}!
Thank you!'));
}
```
Available Functions
-----------------------------------------------------
`string generateHash(string $mailingList, string $secretAppId, string $recipientAddress)`
`array validateHash(string $secretAppId, string $uniqueHash)`
More Documentation
------------------
See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) for more information.