RetailCRM-Mirror/mailgun-php
1
0
Fork 0
mirror of https://github.com/retailcrm/mailgun-php.git synced 2025-02-11 10:49:23 +03:00
Code Issues Projects Releases Wiki Activity

README.md adjustments

Browse Source
This commit is contained in:
Travis Swientek 2013-08-16 12:50:29 -07:00
parent 07837600e6
commit 4ff1184b0b
3 changed files with 229 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/Mailgun/Lists/OptInHandler.php
View File

@ -27,7 +27,8 @@ class OptInHandler{
$concatStrings = $secretAppId . "" . $urlParameters->r; $concatStrings = $secretAppId . "" . $urlParameters->r;
if($urlParameters->s == hash('md5', $concatStrings)){ if($urlParameters->s == hash('md5', $concatStrings)){
return true; $returnArray = array('recipientAddress' => $urlParameters->r, 'mailingList' => $mailingList);
return $returnArray;
} }
return false; return false;
} }

96
src/Mailgun/Lists/README Normal file
View File

@ -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' => '<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.
$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' => '<html><body>Hello,<br><br>We've successfully subscribed you to the list, {$mailingList}!
<br><br>Thank you!</body></html>'));
}
```
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.

131
src/Mailgun/Messages/README.md Normal file
View File

@ -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.