diff --git a/src/Mailgun/Lists/README b/src/Mailgun/Lists/README.md
similarity index 60%
rename from src/Mailgun/Lists/README
rename to src/Mailgun/Lists/README.md
index d92333e..d6d9872 100644
--- a/src/Mailgun/Lists/README
+++ b/src/Mailgun/Lists/README.md
@@ -10,13 +10,13 @@ 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]
+(Recipient Requests Subscribe) -> [Generate Opt In Link] -> [Email Recipient Opt In Link]
+(Recipient 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)
-----------------------------------------------------
+Usage - Opt-In Handler (Recipient Requests Subscribe)
+-----------------------------------------------------
Here's how to use Opt-In Handler to validate Opt-In requests.
```php
@@ -27,29 +27,29 @@ $domain = "example.com";
# Next, instantiate an OptInHandler object from the SDK.
$optInHandler = $mg->OptInHandler();
-$ Next, generate a hash.
+# Next, define necessary variables and 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.
+# Now, let's send a confirmation to the recipient with our link.
$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!'));
+ '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.
+# 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)
-----------------------------------------------------
+Usage - Opt-In Handler (Recipient Clicks Opt In Link)
+-----------------------------------------------------
Here's how to use Opt-In Handler to validate an Opt-In Hash.
```php
@@ -60,7 +60,7 @@ $domain = "example.com";
# Next, instantiate an OptInHandler object from the SDK.
$optInHandler = $mg->OptInHandler();
-$ Next, grab the hash.
+# Next, grab the hash.
$inboundHash = $_GET['hash'];
$secretPassphrase = 'a_secret_passphrase';
@@ -77,13 +77,20 @@ if($hashValidation){
'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!'));
+ 'to' => 'sally@example.com',
+ 'subject' => 'Please Confirm!',
+ 'html' => 'Hello,
We\'ve successfully subscribed
+ you to the list, {$mailingList}!
Thank you!
+ '));
}
```
+A few notes:
+1. 'a_secret_passphrase' can be anything. It's used as the *key* in hashing, since your email address will vary.
+2. validateHash() will return an array containing the recipient address and list address.
+3. You should *always* send an email confirmation before and after the subscription request.
+4. WARNING: On $_GET['hash'], you need to sanitize this value to prevent malicious attempts to inject code.
+
Available Functions
-----------------------------------------------------
@@ -93,4 +100,4 @@ Available Functions
More Documentation
------------------
-See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) for more information.
\ No newline at end of file
+See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) for more information.