From 143414f1749df78a27f298a7103af52e104b6751 Mon Sep 17 00:00:00 2001 From: Travis Swientek Date: Fri, 16 Aug 2013 12:51:18 -0700 Subject: [PATCH] Rename README to README.md --- src/Mailgun/Lists/{README => README.md} | 45 ++++++++++++++----------- 1 file changed, 26 insertions(+), 19 deletions(-) rename src/Mailgun/Lists/{README => README.md} (60%) 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.