2013-08-16 23:50:29 +04:00
|
|
|
Mailgun - Lists
|
|
|
|
|
====================
|
|
|
|
|
|
|
|
|
|
This is the Mailgun PHP *Lists* utilities.
|
|
|
|
|
|
2013-08-20 01:52:38 +04:00
|
|
|
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.
|
2013-08-16 23:50:29 +04:00
|
|
|
|
|
|
|
|
There is currently one utility provided.
|
|
|
|
|
|
|
|
|
|
OptInHandler: Provides methods for authenticating an OptInRequest.
|
|
|
|
|
|
2013-08-17 01:01:08 +04:00
|
|
|
The typical flow for using this utility would be as follows:
|
|
|
|
|
**Recipient Requests Subscribe** -> [Validate Recipient Address] -> [Generate Opt In Link] -> [Email Recipient Opt In Link]
|
|
|
|
|
**Recipient Clicks Opt In Link** -> [Validate Opt In Link] -> [Subscribe User] -> [Send final confirmation]
|
2013-08-16 23:50:29 +04:00
|
|
|
|
|
|
|
|
The above flow is modeled below.
|
|
|
|
|
|
2013-08-16 23:51:18 +04:00
|
|
|
Usage - Opt-In Handler (Recipient Requests Subscribe)
|
|
|
|
|
-----------------------------------------------------
|
2013-08-16 23:50:29 +04:00
|
|
|
Here's how to use Opt-In Handler to validate Opt-In requests.
|
|
|
|
|
|
|
|
|
|
```php
|
2013-08-17 01:01:08 +04:00
|
|
|
# First, instantiate the SDK with your API credentials, domain, and required parameters for example.
|
|
|
|
|
$mg = new Mailgun('key-example');
|
|
|
|
|
$mgValidate = new Mailgun('pub-key-example');
|
2013-08-16 23:50:29 +04:00
|
|
|
|
2013-08-17 01:01:08 +04:00
|
|
|
$domain = 'example.com';
|
2013-08-16 23:50:29 +04:00
|
|
|
$mailingList = 'youlist@example.com';
|
|
|
|
|
$secretPassphrase = 'a_secret_passphrase';
|
2013-08-17 01:01:08 +04:00
|
|
|
$recipientAddress = 'recipient@example.com';
|
|
|
|
|
|
|
|
|
|
# Let's validate the customer's email address, using Mailgun's validation endpoint.
|
|
|
|
|
$result = $mgValidate->get('address/validate', array('address' => $recipientAddress));
|
|
|
|
|
|
|
|
|
|
if($result->http_response_body->is_valid == true){
|
|
|
|
|
# Next, instantiate an OptInHandler object from the SDK.
|
|
|
|
|
$optInHandler = $mg->OptInHandler();
|
|
|
|
|
|
|
|
|
|
# Next, generate a hash.
|
|
|
|
|
$generatedHash = $optInHandler->generateHash($mailingList, $secretPassphrase, $recipientAddress);
|
|
|
|
|
|
|
|
|
|
# Now, let's send a confirmation to the recipient with our link.
|
|
|
|
|
$mg->sendMessage($domain, array('from' => 'bob@example.com',
|
|
|
|
|
'to' => $recipientAddress,
|
|
|
|
|
'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("lists/$mailingList/members", array('address' => $recipientAddress,
|
|
|
|
|
'subscribed' => 'no',
|
|
|
|
|
'upsert' => 'yes'));
|
|
|
|
|
}
|
2013-08-16 23:50:29 +04:00
|
|
|
```
|
|
|
|
|
|
2013-08-16 23:51:18 +04:00
|
|
|
Usage - Opt-In Handler (Recipient Clicks Opt In Link)
|
|
|
|
|
-----------------------------------------------------
|
2013-08-16 23:50:29 +04:00
|
|
|
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.
|
2013-08-17 01:01:08 +04:00
|
|
|
$mg = new Mailgun('key-example');
|
|
|
|
|
$domain = 'example.com';
|
2013-08-16 23:50:29 +04:00
|
|
|
|
|
|
|
|
# Next, instantiate an OptInHandler object from the SDK.
|
|
|
|
|
$optInHandler = $mg->OptInHandler();
|
|
|
|
|
|
2013-08-16 23:51:18 +04:00
|
|
|
# Next, grab the hash.
|
2013-08-16 23:50:29 +04:00
|
|
|
$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'];
|
|
|
|
|
|
2013-08-17 01:01:08 +04:00
|
|
|
$mg->put("lists/$validatedList/members/$validatedRecipient",
|
|
|
|
|
array('address' => $validatedRecipient,
|
|
|
|
|
'subscribed' => 'yes'));
|
2013-08-16 23:50:29 +04:00
|
|
|
|
|
|
|
|
$mg->sendMessage($domain, array('from' => 'bob@example.com',
|
2013-08-17 01:01:08 +04:00
|
|
|
'to' => $validatedRecipient,
|
|
|
|
|
'subject' => 'Confirmation Received!',
|
|
|
|
|
'html' => "<html><body>Hello,<br><br>We've successfully subscribed
|
|
|
|
|
you to the list, $validatedList!<br><br>Thank you!
|
|
|
|
|
</body></html>"));
|
2013-08-16 23:50:29 +04:00
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2013-08-16 23:51:18 +04:00
|
|
|
A few notes:
|
2013-08-20 01:52:38 +04:00
|
|
|
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.
|
2013-08-16 23:51:18 +04:00
|
|
|
|
2013-08-16 23:50:29 +04:00
|
|
|
Available Functions
|
|
|
|
|
-----------------------------------------------------
|
|
|
|
|
|
|
|
|
|
`string generateHash(string $mailingList, string $secretAppId, string $recipientAddress)`
|
|
|
|
|
|
|
|
|
|
`array validateHash(string $secretAppId, string $uniqueHash)`
|
|
|
|
|
|
|
|
|
|
More Documentation
|
|
|
|
|
------------------
|
2013-08-20 01:52:38 +04:00
|
|
|
See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html)
|
|
|
|
|
for more information.
|
