Rename README to README.md

mailgun · Aug 16, 2013 · 143414f · 143414f
1 parent 4ff1184
commit 143414f
Showing 1 changed file with 26 additions and 19 deletions.
diff --git a/src/Mailgun/Lists/README → src/Mailgun/Lists/README.md b/src/Mailgun/Lists/README → 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'    => '<html><body>Hello,<br><br>You have requested to be subscribed to the mailing list {$mailingList}. 
-                                			  Please <a href="http://yourdomain.com/subscribe.php?hash=$generatedHash">confirm</a> your subscription.
-                                			  <br><br>Thank you!</body></html>'));
+                                'html'    => '<html><body>Hello,<br><br>You have requested to be subscribed 
+                                			  to the mailing list {$mailingList}. Please <a 
+                                			  href="http://yourdomain.com/subscribe.php?hash=$generatedHash">confirm
+                                			  </a> your subscription.<br><br>Thank you!</body></html>'));
 
-$ 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'    => '<html><body>Hello,<br><br>We've successfully subscribed you to the list, {$mailingList}!
-                                			  <br><br>Thank you!</body></html>'));
+                                    'to'      => 'sally@example.com', 
+                                    'subject' => 'Please Confirm!', 
+                                    'html'    => '<html><body>Hello,<br><br>We\'ve successfully subscribed 
+                                	              you to the list, {$mailingList}!<br><br>Thank you!
+                                	              </body></html>'));
 }
 ```
 
+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.
+See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) for more information.