diff --git a/src/Mailgun/Lists/OptInHandler.php b/src/Mailgun/Lists/OptInHandler.php index 5fed661..6c5990a 100644 --- a/src/Mailgun/Lists/OptInHandler.php +++ b/src/Mailgun/Lists/OptInHandler.php @@ -27,7 +27,8 @@ class OptInHandler{ $concatStrings = $secretAppId . "" . $urlParameters->r; if($urlParameters->s == hash('md5', $concatStrings)){ - return true; + $returnArray = array('recipientAddress' => $urlParameters->r, 'mailingList' => $mailingList); + return $returnArray; } return false; } diff --git a/src/Mailgun/Lists/README b/src/Mailgun/Lists/README new file mode 100644 index 0000000..d92333e --- /dev/null +++ b/src/Mailgun/Lists/README @@ -0,0 +1,96 @@ +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. \ No newline at end of file diff --git a/src/Mailgun/Messages/README.md b/src/Mailgun/Messages/README.md new file mode 100644 index 0000000..35f3a48 --- /dev/null +++ b/src/Mailgun/Messages/README.md @@ -0,0 +1,131 @@ +Mailgun - Messages +==================== + +This is the Mailgun PHP *Message* 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 are two utilities included, Message Builder and Batch Message. + +Message Builder: Allows you to build a message object by calling methods for each MIME attribute. +Batch Message: Inherits Message Builder and allows you to iterate through recipients from a list. Messages will fire after the 1,000th recipient has been added. + +Usage - Message Builder +----------------------- +Here's how to use Message Builder to build your Message. + +```php +# First, instantiate the SDK with your API credentials and define your domain. +$mg = new Mailgun("key-example"); +$domain = "example.com"; + +# Next, instantiate a Message Builder object from the SDK. +$messageBldr = $mg->MessageBuilder(); + +# Define the from address. +$messageBldr->setFromAddress("me@example.com", array("first"=>"PHP", "last" => "SDK")); +# Define a to recipient. +$messageBldr->addToRecipient("john.doe@example.com", array("first" => "John", "last" => "Doe")); +# Define a cc recipient. +$messageBldr->addCcRecipient("sally.doe@example.com", array("first" => "Sally", "last" => "Doe")); +# Define the subject. +$messageBldr->setSubject("A message from the PHP SDK using Message Builder!"); +# Define the body of the message. +$messageBldr->setTextBody("This is the text body of the message!"); + +# Other Optional Parameters. +$messageBldr->addCampaignId("My-Awesome-Campaign"); +$messageBldr->addCustomHeader("Customer-Id", "12345"); +$messageBldr->addAttachment("@/tron.jpg"); +$messageBldr->setDeliveryTime("tomorrow 8:00AM", "PST"); +$messageBldr->setClickTracking(true); + +# Finally, send the message. +$mg->post('{$domain}/messages', $messageBldr->getMessage()); +``` + +Available Functions +----------------------------------------------------- + +`string addToRecipient(string $address, array $attributes)` + +`string addCcRecipient(string $address, array $attributes)` + +`string addBccRecipient(string $address, array $attributes)` + +`string setFromAddress(string $address, array $attributes)` + +`string setSubject(string $subject)` + +`string setTextBody(string $textBody)` + +`string setHtmlBody(string $htmlBody)` + +`bool addAttachment(string $attachmentPath)` + +`bool addInlineImage(string $inlineImagePath)` + +`string setTestMode(bool $testMode)` + +`string addCampaignId(string $campaignId)` + +`string setDkim(bool $enabled)` + +`string setOpenTracking($enabled)` + +`string setClickTracking($enabled)` + +`string setDeliveryTime(string $timeDate, string $timeZone)` + +`string addCustomData(string $optionName, string $data)` + +`string addCustomParameter(string $parameterName, string $data)` + +`array getMessage()` + +`array getFiles()` + + +Usage - Batch Message +--------------------- +Here's how to use Batch Message to easily handle batch sending jobs. + +```php +# First, instantiate the SDK with your API credentials and define your domain. +$mg = new Mailgun("key-example"); +$domain = "example.com"; + +# Next, instantiate a Message Builder object from the SDK, pass in your sending domain. +$batchMsg = $mg->BatchMessage($domain); + +# Define the from address. +$batchMsg->setFromAddress("me@samples.mailgun.org", array("first"=>"PHP", "last" => "SDK")); +# Define the subject. +$batchMsg->setSubject("A Batch Message from the PHP SDK!"); +# Define the body of the message. +$batchMsg->setTextBody("This is the text body of the message!"); + +# Next, let's add a few recipients to the batch job. +$batchMsg->addToRecipient("john.doe@samples.mailgun.org", array("first" => "John", "last" => "Doe")); +$batchMsg->addToRecipient("sally.doe@samples.mailgun.org", array("first" => "Sally", "last" => "Doe")); +$batchMsg->addToRecipient("mike.jones@samples.mailgun.org", array("first" => "Mike", "last" => "Jones")); +... +// After 1,000 recipeints, Batch Message will automatically post your message to the messages endpoint. + +// Call finalize() to send any remaining recipients still in the buffer. +$batchMsg->finalize(); + +``` + +Available Functions (Inherits all Batch Message and Messages Functions) +----------------------------------------------------------------------- + +`addToRecipient(string $address, string $attributes)` + +`sendMessage(array $message, array $files)` + +`array finalize()` + +More Documentation +------------------ +See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) for more information.