mirror of
https://github.com/retailcrm/mailgun-php.git
synced 2025-02-06 08:19:25 +03:00
README.md adjustments
This commit is contained in:
Travis Swientek
parent
07837600e6
commit
4ff1184b0b
@ -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;
|
||||
}
|
||||
|
||||
96
src/Mailgun/Lists/README
Normal file
96
src/Mailgun/Lists/README
Normal 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
131
src/Mailgun/Messages/README.md
Normal 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.
|
||||
Loading…
x
Reference in New Issue
Block a user