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 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]

The above flow is modeled below.

Here's how to use Opt-In Handler to validate Opt-In requests.

# 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');

$domain = 'example.com';
$mailingList = 'youlist@example.com';
$secretPassphrase = 'a_secret_passphrase';
$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'));
}

Usage - Opt-In Handler (Recipient Clicks Opt In Link)

Here's how to use Opt-In Handler to validate an Opt-In Hash.

# 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("lists/$validatedList/members/$validatedRecipient", 
						array('address'    => $validatedRecipient, 
                              'subscribed' => 'yes'));
    
    $mg->sendMessage($domain, array('from'    => 'bob@example.com', 
                                    '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>"));
}

A few notes:

'a_secret_passphrase' can be anything. It's used as the key in hashing, since your email address will vary.
validateHash() will return an array containing the recipient address and list address.
You should always send an email confirmation before and after the subscription request.
WARNING: On $_GET['hash'], you need to sanitize this value to prevent malicious attempts to inject code.

Available Functions

string generateHash(string $mailingList, string $secretAppId, string $recipientAddress)

array validateHash(string $secretAppId, string $uniqueHash)

4.8 KiB Raw Blame History

Mailgun - Lists

Usage - Opt-In Handler (Recipient Requests Subscribe)

Usage - Opt-In Handler (Recipient Clicks Opt In Link)

Available Functions

More Documentation

4.8 KiB

Raw Blame History