From 6b6a13b9bc79d30b5471c45ba70c6dde04a1c11a Mon Sep 17 00:00:00 2001 From: Travis Swientek Date: Fri, 2 Aug 2013 13:25:02 -0700 Subject: [PATCH] Added README across endpoints [ci skip] --- src/Mailgun/Address/README.md | 15 ++- src/Mailgun/Bounces/README.md | 38 ++++++ src/Mailgun/Campaigns/README.md | 53 +++++++++ src/Mailgun/Complaints/README.md | 37 ++++++ src/Mailgun/Lists/README.md | 53 +++++++++ src/Mailgun/Logs/README.md | 31 +++++ src/Mailgun/Messages/MessageBuilder.php | 90 +++++++-------- src/Mailgun/Messages/README.md | 146 ++++++++++++++++++++++++ src/Mailgun/Routes/README.md | 39 +++++++ src/Mailgun/Stats/README.md | 32 ++++++ src/Mailgun/Unsubscribes/README.md | 37 ++++++ 11 files changed, 522 insertions(+), 49 deletions(-) create mode 100644 src/Mailgun/Bounces/README.md create mode 100644 src/Mailgun/Campaigns/README.md create mode 100644 src/Mailgun/Complaints/README.md create mode 100644 src/Mailgun/Lists/README.md create mode 100644 src/Mailgun/Logs/README.md create mode 100644 src/Mailgun/Messages/README.md create mode 100644 src/Mailgun/Routes/README.md create mode 100644 src/Mailgun/Stats/README.md create mode 100644 src/Mailgun/Unsubscribes/README.md diff --git a/src/Mailgun/Address/README.md b/src/Mailgun/Address/README.md index b983f02..a073f35 100644 --- a/src/Mailgun/Address/README.md +++ b/src/Mailgun/Address/README.md @@ -1,11 +1,11 @@ -Mailgun-PHP/Address +Mailgun - Address =================== This is the Mailgun PHP *Email Validation* endpoint. Given an arbitrary address, we will validate the address based on: Syntax checks (RFC defined grammar), DNS validation, Spell checks, Email Service Provider (ESP) specific local-part grammar (if available). 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. -Address Usage +Usage ------------- Here's how to use the "Address" API endpoint: @@ -18,6 +18,13 @@ $address = $mgClient->Address(); # Now, validate the address and store the result in $result. $result = $address->validateAddress("me@samples.mailgun.org"); - -echo $result; ``` + +Available Functions +------------------- + +`validateAddress(string $address);` + +More Documentation +------------------ +See the official [Mailgun Docs](http://documentation.mailgun.com/api-email-validation.html) for more information. \ No newline at end of file diff --git a/src/Mailgun/Bounces/README.md b/src/Mailgun/Bounces/README.md new file mode 100644 index 0000000..b92e574 --- /dev/null +++ b/src/Mailgun/Bounces/README.md @@ -0,0 +1,38 @@ +Mailgun - Bounces +=================== + +This is the Mailgun PHP *Bounces* endpoint. + +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. + +Usage +------------- +Here's how to use the "Bounces" API endpoint: + +```php +# First, instantiate the client with your PUBLIC API credentials and domain. +$mgClient = new MailgunClient("pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7", "samples.mailgun.org"); + +# Next, instantiate a Bounces object on the Bounces API endpoint. +$bounces = $mgClient->Bounces(); + +# Finally, add an address to the Bounces Table. +$result = $bounces->addAddress("bounce@samples.mailgun.org", 550, "Server not accepting messages for mailbox."); + +``` + +Available Functions +------------------- + +`addAddress(string $bounceAddress, int $bounceCode, string $bounceError);` + +`deleteAddress(string $bounceAddress);` + +`getBounce(string $bounceAddress);` + +`getBounces(int $limit, int $skip);` + + +More Documentation +------------------ +See the official [Mailgun Docs](http://documentation.mailgun.com/api-bounces.html) for more information. \ No newline at end of file diff --git a/src/Mailgun/Campaigns/README.md b/src/Mailgun/Campaigns/README.md new file mode 100644 index 0000000..a70315e --- /dev/null +++ b/src/Mailgun/Campaigns/README.md @@ -0,0 +1,53 @@ +Mailgun - Campaigns +=================== + +This is the Mailgun PHP *Campaigns* endpoint. + +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. + +Usage +------------- +Here's how to use the "Campaign" API endpoint: + +```php +# First, instantiate the client with your PUBLIC API credentials and domain. +$mgClient = new MailgunClient("pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7", "samples.mailgun.org"); + +# Next, instantiate a Campaign object on the Campaign API endpoint. +$campaigns = $mgClient->Campaigns(); + +$ Finally, get a list of campaigns, limit 5, skip 0. +$campaigns->getCampaigns(5, 0); + +``` + +Available Functions +------------------- + +`getCampaigns(int $limit, int $skip)` + +`getCampaign(string $campaignId)` + +`addCampaign(string $name, string $id)` + +`updateCampaign(string $campaignId, string $name, string $id)` + +`deleteCampaign(string $campaignId)` + +`getCampaignEvents(string $campaignId, array $filterParams)` + +`getCampaignStats(string $campaignId, array $filterParams)` + +`getCampaignClicks(string $campaignId, array $filterParams)` + +`getCampaignOpens(string $campaignId, array $filterParams)` + +`getCampaignUnsubscribes(string $campaignId, array $filterParams)` + +`getCampaignComplaints(string $campaignId, array $filterParams)` + +$filterParams are unique to the endpoint being called. See the documentation below for specifics. + +More Documentation +------------------ +See the official [Mailgun Docs](http://documentation.mailgun.com/api-campaigns.html) for more information. \ No newline at end of file diff --git a/src/Mailgun/Complaints/README.md b/src/Mailgun/Complaints/README.md new file mode 100644 index 0000000..c313243 --- /dev/null +++ b/src/Mailgun/Complaints/README.md @@ -0,0 +1,37 @@ +Mailgun - Complaints +==================== + +This is the Mailgun PHP *Complaints* endpoint. + +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. + +Usage +------------- +Here's how to use the "Complaints" API endpoint: + +```php +# First, instantiate the client with your PUBLIC API credentials and domain. +$mgClient = new MailgunClient("pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7", "samples.mailgun.org"); + +# Next, instantiate a Complaints object on the Complaints API endpoint. +$complaints = $mgClient->Complaints(); + +# Finally, add a complaint to the Spam Complaints table. +$result = $complaints->addAddress("junk@samples.mailgun.org"); + +``` + +Available Functions +------------------- + +`addAddress(string $spamAddress)` + +`deleteAddress(string $spamAddress)` + +`getComplaint(string $spamAddress)` + +`getComplaints(int $limit, int $skip)` + +More Documentation +------------------ +See the official [Mailgun Docs](http://documentation.mailgun.com/api-complaints.html) for more information. \ No newline at end of file diff --git a/src/Mailgun/Lists/README.md b/src/Mailgun/Lists/README.md new file mode 100644 index 0000000..e921411 --- /dev/null +++ b/src/Mailgun/Lists/README.md @@ -0,0 +1,53 @@ +Mailgun - Lists +==================== + +This is the Mailgun PHP *Lists* endpoint. + +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. + +Usage +------------- +Here's how to use the "Lists" API endpoint: + +```php +# First, instantiate the client with your PUBLIC API credentials and domain. +$mgClient = new MailgunClient("pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7", "samples.mailgun.org"); + +# Next, instantiate a Lists object on the Lists API endpoint. +$lists = $mgClient->Lists(); + +# Finally, get 50 results and store in $result. +$result = $lists->getLists(50, 0); + +``` + +Available Functions +------------------- + +`getLists(int $limit, int $skip)` + +`getList(string $listAddress)` + +`addList(string $listAddress, string $name, string $description, string $access_level)` + +`updateList(string $listAddress, string $name, string $description, string $access_level)` + +`deleteList(string $listAddress)` + +`getListMembers(string $listAddress, array $filterParams)` + +`getListMember(string $listAddress, string $memberAddress)` + +`addListMember(string $listAddress, string $memberAddress, string $name, array $vars, bool $subscribed, bool $upsert)` + +`updateListMember(string $listAddress, string $memberAddress, string $name, array $vars, bool $subscribed)` + +`deleteListMember(string $listAddress, string $memberAddress)` + +`getListStats(string $listAddress)` + + + +More Documentation +------------------ +See the official [Mailgun Docs](http://documentation.mailgun.com/api-mailinglists.html) for more information. \ No newline at end of file diff --git a/src/Mailgun/Logs/README.md b/src/Mailgun/Logs/README.md new file mode 100644 index 0000000..ca544f8 --- /dev/null +++ b/src/Mailgun/Logs/README.md @@ -0,0 +1,31 @@ +Mailgun - Logs +==================== + +This is the Mailgun PHP *Logs* endpoint. + +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. + +Usage +------------- +Here's how to use the "Logs" API endpoint: + +```php +# First, instantiate the client with your PUBLIC API credentials and domain. +$mgClient = new MailgunClient("pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7", "samples.mailgun.org"); + +# Next, instantiate a Logs object on the Logs API endpoint. +$logs = $mgClient->Logs(); + +# Finally, get the 50 most recent log items. +$result = $logs->getLogs(50, 0); + +``` + +Available Functions +------------------- + +`getLogs(int $limit, int $skip)` + +More Documentation +------------------ +See the official [Mailgun Docs](http://documentation.mailgun.com/api-logs.html) for more information. \ No newline at end of file diff --git a/src/Mailgun/Messages/MessageBuilder.php b/src/Mailgun/Messages/MessageBuilder.php index 5cb7399..961a956 100644 --- a/src/Mailgun/Messages/MessageBuilder.php +++ b/src/Mailgun/Messages/MessageBuilder.php @@ -138,45 +138,45 @@ class MessageBuilder extends Messages{ return true; } - public function setSubject($data = NULL){ - if($data == NULL || $data == ""){ - $data = " "; + public function setSubject($subject = NULL){ + if($subject == NULL || $subject == ""){ + $subject = " "; } - $this->message['subject'] = $data; + $this->message['subject'] = $subject; return true; } - public function addCustomHeader($headerName, $data){ + public function addCustomHeader($headerName, $headerData){ if(!preg_match("/^h:/i", $headerName)){ $headerName = "h:" . $headerName; } - $this->message[$headerName] = array($data); + $this->message[$headerName] = array($headerData); return true; } - public function setTextBody($data){ - if($data == NULL || $data == ""){ - $data = " "; + public function setTextBody($textBody){ + if($textBody == NULL || $textBody == ""){ + $textBody = " "; } - $this->message['text'] = $data; + $this->message['text'] = $textBody; return true; } - public function setHtmlBody($data){ - if($data == NULL || $data == ""){ - $data = " "; + public function setHtmlBody($htmlBody){ + if($htmlBody == NULL || $htmlBody == ""){ + $htmlBody = " "; } - $this->message['html'] = $data; + $this->message['html'] = $htmlBody; return true; } - public function addAttachment($data){ - if(preg_match("/^@/", $data)){ + public function addAttachment($attachmentPath){ + if(preg_match("/^@/", $attachmentPath)){ if(isset($this->files["attachment"])){ - array_push($this->files["attachment"], $data); + array_push($this->files["attachment"], $attachmentPath); } else{ - $this->files["attachment"] = array($data); + $this->files["attachment"] = array($attachmentPath); } return true; } @@ -185,14 +185,14 @@ class MessageBuilder extends Messages{ } } - public function addInlineImage($data){ - if(preg_match("/^@/", $data)){ + public function addInlineImage($inlineImagePath){ + if(preg_match("/^@/", $inlineImagePath)){ if(isset($this->files['inline'])){ - array_push($this->files['inline'] , $data); + array_push($this->files['inline'] , $inlineImagePath); return true; } else{ - $this->files['inline'] = array($data); + $this->files['inline'] = array($inlineImagePath); return true; } } @@ -201,24 +201,24 @@ class MessageBuilder extends Messages{ } } - public function setTestMode($data){ - if(filter_var($data, FILTER_VALIDATE_BOOLEAN)){ - $data = "yes"; + public function setTestMode($testMode){ + if(filter_var($testMode, FILTER_VALIDATE_BOOLEAN)){ + $testMode = "yes"; } else{ - $data = "no"; + $testMode = "no"; } - $this->message['o:testmode'] = $data; + $this->message['o:testmode'] = $testMode; return true; } - public function addCampaignId($data){ + public function addCampaignId($campaignId){ if($this->campaignIdCount < 3){ if(isset($this->message['o:campaign'])){ - array_push($this->message['o:campaign'] , $data); + array_push($this->message['o:campaign'] , $campaignId); } else{ - $this->message['o:campaign'] = array($data); + $this->message['o:campaign'] = array($campaignId); } $this->campaignIdCount++; return true; @@ -228,36 +228,36 @@ class MessageBuilder extends Messages{ } } - public function setDkim($data){ - if(filter_var($data, FILTER_VALIDATE_BOOLEAN)){ - $data = "yes"; + public function setDkim($enabled){ + if(filter_var($enabled, FILTER_VALIDATE_BOOLEAN)){ + $enabled = "yes"; } else{ - $data = "no"; + $enabled = "no"; } - $this->message["o:dkim"] = $data; + $this->message["o:dkim"] = $enabled; return true; } - public function setOpenTracking($data){ - if(filter_var($data, FILTER_VALIDATE_BOOLEAN)){ - $data = "yes"; + public function setOpenTracking($enabled){ + if(filter_var($enabled, FILTER_VALIDATE_BOOLEAN)){ + $enabled = "yes"; } else{ - $data = "no"; + $enabled = "no"; } - $this->message['o:tracking-opens'] = $data; + $this->message['o:tracking-opens'] = $enabled; return true; } - public function setClickTracking($data){ - if(filter_var($data, FILTER_VALIDATE_BOOLEAN)){ - $data = "yes"; + public function setClickTracking($enabled){ + if(filter_var($enabled, FILTER_VALIDATE_BOOLEAN)){ + $enabled = "yes"; } else{ - $data = "no"; + $enabled = "no"; } - $this->message['o:tracking-clicks'] = $data; + $this->message['o:tracking-clicks'] = $enabled; return true; } diff --git a/src/Mailgun/Messages/README.md b/src/Mailgun/Messages/README.md new file mode 100644 index 0000000..ed79ec0 --- /dev/null +++ b/src/Mailgun/Messages/README.md @@ -0,0 +1,146 @@ +Mailgun - Messages +==================== + +This is the Mailgun PHP *Messages* endpoint. + +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. + +Usage - Messages +---------------- +Here's how to use the "Messages" API endpoint: + +```php +# First, instantiate the client with your PUBLIC API credentials and domain. +$mgClient = new MailgunClient("pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7", "samples.mailgun.org"); + +# Next, instantiate a Message object on the Messages API endpoint. +$message = $mgClient->Messages(); + +# Next, set the message content. +$message->setMessage(array('from' => 'me@samples.mailgun.org', + 'to' => 'php-sdk@mailgun.net', + 'subject' => 'The PHP SDK is awesome!', + 'text' => 'It is so simple to send a message.')); + +# Finally, send the message. +$message->sendMessage(); +``` + +Available Functions +------------------- + +`sendMessage(array $message, array $files)` + +`setMessage(array $message, array $files)` + +`sendMessage()` + + +Usage - Message Builder +--------------------- +Here's how to use the "Messages" API endpoint with Message Builder: + +```php +# First, instantiate the client with your PUBLIC API credentials and domain. +$mgClient = new MailgunClient("pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7", "samples.mailgun.org"); + +# Next, instantiate a Message Builder object on the Messages API endpoint. +$messageBldr = $mgClient->Messages()->MessageBuilder(); + +# Define the from address. +$messageBldr->setFromAddress("me@samples.mailgun.org", array("first"=>"PHP", "last" => "SDK")); +# Define a to recipient. +$messageBldr->addToRecipient("john.doe@samples.mailgun.org", array("first" => "John", "last" => "Doe")); +# Define a cc recipient. +$messageBldr->addCcRecipient("sally.doe@samples.mailgun.org", 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. +$messageBldr->sendMessage(); +``` + +Available Functions (Inherits all Messages Functions) +----------------------------------------------------- + +`addToRecipient(string $address, array $attributes)` + +`addCcRecipient(string $address, array $attributes)` + +`addBccRecipient(string $address, array $attributes)` + +`setFromAddress(string $address, array $attributes)` + +`setSubject(string $subject)` + +`setTextBody(string $textBody)` + +`setHtmlBody(string $htmlBody)` + +`addAttachment(string $attachmentPath)` + +`addInlineImage(string $inlineImagePath)` + +`setTestMode(bool $testMode)` + +`addCampaignId(string $campaignId)` + +`setDkim(bool $enabled)` + +`setOpenTracking($enabled)` + +`setClickTracking($enabled)` + +`setDeliveryTime(string $timeDate, string $timeZone)` + +`addCustomOption(string $optionName, string $data)` + +`getMessage()` + +`getFiles()` + + +Usage - Batch Sending +--------------------- +Here's how to use the "Messages" API endpoint with Batch Sending: + +```php +# First, instantiate the client with your API credentials and domain. +$mgClient = new MailgunClient("key-3ax6xnjp29jd6fds4gc373sgvjxteol0", "samples.mailgun.org"); + +# Next, instantiate a Batch Message object on the Messages API endpoint. +$batchMessage = $mgClient->Messages()->BatchMessage(); + +# Define the from address. +$batchMessage->setFromAddress("me@samples.mailgun.org", array("first"=>"PHP", "last" => "SDK")); +# Define the subject. +$batchMessage->setSubject("A Batch Message from the PHP SDK!"); +# Define the body of the message. +$batchMessage->setTextBody("This is the text body of the message!"); + +# Next, let's add a few recipients to the batch job. +$batchMessage->addBatchRecipient("john.doe@samples.mailgun.org", array("first" => "John", "last" => "Doe")); +$batchMessage->addBatchRecipient("sally.doe@samples.mailgun.org", array("first" => "Sally", "last" => "Doe")); +$batchMessage->addBatchRecipient("mike.jones@samples.mailgun.org", array("first" => "Mike", "last" => "Jones")); + +# Finally, submit the batch job. +$batchMessage->sendMessage(); +``` + +Available Functions (Inherits all Batch Message and Messages Functions) +----------------------------------------------------------------------- + +`addBatchRecipient(string $address, string $attributes)` + +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/Routes/README.md b/src/Mailgun/Routes/README.md new file mode 100644 index 0000000..f708853 --- /dev/null +++ b/src/Mailgun/Routes/README.md @@ -0,0 +1,39 @@ +Mailgun - Routes +==================== + +This is the Mailgun PHP *Routes* endpoint. + +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. + +Usage +------------- +Here's how to use the "Routes" API endpoint: + +```php +# First, instantiate the client with your PUBLIC API credentials and domain. +$mgClient = new MailgunClient("pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7", "samples.mailgun.org"); + +# Next, instantiate a Routes object on the Routes API endpoint. +$routes = $mgClient->Routes(); + +# Next, add the new route. +$routes->addRoute(0, "Match defined recipient", "match_recipient(\"^chris\+(.*)@example.com$\")", "forward(\"mbx@externaldomain.com\")"); +``` + +Available Functions +------------------- + +`getRoutes(int $limit, int $skip)` + +`getRoute(string $routeId)` + +`addRoute(int $priority, string $description, string $expression, string $action)` + +`updateRoute(string $routeId, int $priority, string $description, string $expression, string $action)` + +`deleteRoute(string $routeId)` + + +More Documentation +------------------ +See the official [Mailgun Docs](http://documentation.mailgun.com/api-routes.html) for more information. \ No newline at end of file diff --git a/src/Mailgun/Stats/README.md b/src/Mailgun/Stats/README.md new file mode 100644 index 0000000..3cf106b --- /dev/null +++ b/src/Mailgun/Stats/README.md @@ -0,0 +1,32 @@ +Mailgun - Stats +==================== + +This is the Mailgun PHP *Stats* endpoint. + +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. + +Usage +------------- +Here's how to use the "Stats" API endpoint: + +```php +# First, instantiate the client with your PUBLIC API credentials and domain. +$mgClient = new MailgunClient("pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7", "samples.mailgun.org"); + +# Next, instantiate a Stats object on the Stats API endpoint. +$stats = $mgClient->Stats(); + +# Next, get the last 50 stats. +$stats->getStats(50, 0); +``` + +Available Functions +------------------- + +`deleteTag(string $tag)` + +`getStats(int $limit, int $skip)` + +More Documentation +------------------ +See the official [Mailgun Docs](http://documentation.mailgun.com/api-stats.html) for more information. \ No newline at end of file diff --git a/src/Mailgun/Unsubscribes/README.md b/src/Mailgun/Unsubscribes/README.md new file mode 100644 index 0000000..a75ef85 --- /dev/null +++ b/src/Mailgun/Unsubscribes/README.md @@ -0,0 +1,37 @@ +Mailgun - Unsubscribes +====================== + +This is the Mailgun PHP *Unsubscribes* endpoint. + +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. + +Usage +------------- +Here's how to use the "Unsubscribes" API endpoint: + +```php +# First, instantiate the client with your PUBLIC API credentials and domain. +$mgClient = new MailgunClient("pubkey-5ogiflzbnjrljiky49qxsiozqef5jxp7", "samples.mailgun.org"); + +# Next, instantiate a Unsubscribes object on the Unsubscribes API endpoint. +$unsubscribe = $mgClient->Unsubscribes(); + +# Next, unsubscribe the address from the weekly-emails tag. +$unsubscribe->addAddress("removeme@samples.mailgun.org", "weekly-emails"); +``` + +Available Functions +------------------- + +`addAddress(string $unsubAddress, string $unsubTag)` + +`deleteAddress(string $unsubAddress)` + +`getUnsubscribe(string $unsubAddress)` + +`getUnsubscribes(int $limit, int $skip)` + + +More Documentation +------------------ +See the official [Mailgun Docs](http://documentation.mailgun.com/api-unsubscribes.html) for more information. \ No newline at end of file