Updated README

This commit is contained in:
Travis Swientek 2013-08-19 14:52:38 -07:00
parent 52808cc565
commit 89a2e8bd09
3 changed files with 64 additions and 31 deletions

View File

@ -2,16 +2,20 @@ Mailgun-PHP
=========== ===========
[![Build Status](https://travis-ci.org/travelton/Mailgun-PHP.png?branch=master)](https://travis-ci.org/travelton/Mailgun-PHP) [![Build Status](https://travis-ci.org/travelton/Mailgun-PHP.png?branch=master)](https://travis-ci.org/travelton/Mailgun-PHP)
This is the Mailgun PHP SDK. This SDK contains methods for easily interacting with the Mailgun API. This is the Mailgun PHP SDK. This SDK contains methods for easily interacting
Below are examples to get you started. For additional examples, please see our official documentation with the Mailgun API.
Below are examples to get you started. For additional examples, please see our
official documentation
at http://documentation.mailgun.com at http://documentation.mailgun.com
Current Release: 0.7 Current Release: 0.7
Installation Installation
------------ ------------
To install the SDK, you will need to be using [Composer](http://getcomposer.org/) in your project. To install the SDK, you will need to be using [Composer](http://getcomposer.org/)
If you aren't using Composer yet, it's really simple! Here's how to install composer and the Mailgun SDK. in your project.
If you aren't using Composer yet, it's really simple! Here's how to install
composer and the Mailgun SDK.
```PHP ```PHP
# Install Composer # Install Composer
@ -21,12 +25,14 @@ curl -sS https://getcomposer.org/installer | php
php composer.phar require mailgun/mailgun-php:~0.7 php composer.phar require mailgun/mailgun-php:~0.7
``` ```
For shared hosts with SSH access, you might need to run this instead (contact your shared host for assistance): For shared hosts with SSH access, you might need to run this instead (contact
your shared host for assistance):
``` ```
php -d detect_unicode=Off -r "eval('?>'.file_get_contents('https://getcomposer.org/installer'));" php -d detect_unicode=Off -r "eval('?>'.file_get_contents('https://getcomposer.org/installer'));"
``` ```
Next, require Composer's autoloader, in your application, to automatically load the Mailgun SDK in your project: Next, require Composer's autoloader, in your application, to automatically
load the Mailgun SDK in your project:
```PHP ```PHP
require 'vendor/autoload.php'; require 'vendor/autoload.php';
use Mailgun\Mailgun; use Mailgun\Mailgun;
@ -62,7 +68,8 @@ $mg->get("$domain/log", array('limit' => 25,
Result Result
------ ------
The results, provided by the endpoint, are returned as an object, which you can traverse like an array. The results, provided by the endpoint, are returned as an object, which you
can traverse like an array.
Example: Example:
@ -71,16 +78,19 @@ $mg = new Mailgun("key-example");
$domain = "example.com"; $domain = "example.com";
$result = $mg->get("$domain/log", array('limit' => 25, $result = $mg->get("$domain/log", array('limit' => 25,
'skip' => 0); 'skip' => 0);
$httpResponseCode = $result->http_response_code; $httpResponseCode = $result->http_response_code;
$httpResponseBody = $result->http_response_body; $httpResponseBody = $result->http_response_body;
``` ```
Example Contents: Example Contents:
$httpResponseCode will contain an integer. You can find how we use HTTP response codes in our documentation: http://documentation.mailgun.com/api-intro.html?highlight=401#errors **$httpResponseCode** will contain an integer. You can find how we use HTTP response
codes in our documentation:
http://documentation.mailgun.com/api-intro.html?highlight=401#errors
$httpResponseBody will contain an object of the API response. In the above example, a var_dump($result) would contain the following: **$httpResponseBody** will contain an object of the API response. In the above
example, a var_dump($result) would contain the following:
``` ```
["http_response_body"]=> ["http_response_body"]=>
@ -96,7 +106,9 @@ $httpResponseBody will contain an object of the API response. In the above examp
["created_at"]=> ["created_at"]=>
string(29) "Mon, 19 Aug 2013 19:41:33 GMT" string(29) "Mon, 19 Aug 2013 19:41:33 GMT"
["message"]=> ["message"]=>
string(155) "Will retry in 14400 seconds: me@samples.mailgun.org → sergeyo@profista.com 'Hello' No MX for [profista.com] Server response: 498 No MX for [profista.com]" string(155) "Will retry in 14400 seconds: me@samples.mailgun.org →
sergeyo@profista.com 'Hello' No MX for [profista.com] Server response:
498 No MX for [profista.com]"
["type"]=> ["type"]=>
string(4) "warn" string(4) "warn"
["message_id"]=> ["message_id"]=>
@ -106,19 +118,27 @@ $httpResponseBody will contain an object of the API response. In the above examp
} }
``` ```
For usage examples on each API endpoint, head over to our official documentation pages. For usage examples on each API endpoint, head over to our official documentation
pages.
This SDK includes a [Message Builder](src/Mailgun/Messages/README.md) and [Batch Message](src/Mailgun/Messages/README.md) component. This SDK includes a [Message Builder](src/Mailgun/Messages/README.md) and
[Batch Message](src/Mailgun/Messages/README.md) component.
Message Builder allows you to quickly create the array of parameters, required to send a message, by calling a methods for each parameter. Message Builder allows you to quickly create the array of parameters, required
Batch Message is an extension of Message Builder, and allows you to easily send a batch message job within a few seconds. The complexity of to send a message, by calling a methods for each parameter.
Batch Message is an extension of Message Builder, and allows you to easily send
a batch message job within a few seconds. The complexity of
batch messaging is eliminated! batch messaging is eliminated!
Support and Feedback Support and Feedback
-------------------- --------------------
Be sure to visit the Mailgun official [documentation website](http://documentation.mailgun.com/) for additional information about our API. Be sure to visit the Mailgun official
[documentation website](http://documentation.mailgun.com/) for additional
information about our API.
If you find a bug, please submit the issue in Github directly. [Mailgun-PHP Issues](https://github.com/mailgun/Mailgun-PHP/issues) If you find a bug, please submit the issue in Github directly.
[Mailgun-PHP Issues](https://github.com/mailgun/Mailgun-PHP/issues)
As always, if you need additional assistance, drop us a note at [support@mailgun.com](mailto:support@mailgun.com). As always, if you need additional assistance, drop us a note at
[support@mailgun.com](mailto:support@mailgun.com).

View File

@ -3,7 +3,8 @@ Mailgun - Lists
This is the Mailgun PHP *Lists* utilities. 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. 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. There is currently one utility provided.
@ -93,10 +94,14 @@ if($hashValidation){
``` ```
A few notes: A few notes:
1. 'a_secret_passphrase' can be anything. It's used as the *key* in hashing, since your email address will vary. 1. 'a_secret_passphrase' can be anything. It's used as the *key* in hashing,
2. validateHash() will return an array containing the recipient address and list address. since your email address will vary.
3. You should *always* send an email confirmation before and after the subscription request. 2. validateHash() will return an array containing the recipient address and list
4. WARNING: On $_GET['hash'], you need to sanitize this value to prevent malicious attempts to inject code. 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.
Available Functions Available Functions
----------------------------------------------------- -----------------------------------------------------
@ -107,4 +112,5 @@ Available Functions
More Documentation More Documentation
------------------ ------------------
See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) for more information. See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html)
for more information.

View File

@ -3,12 +3,16 @@ Mailgun - Messages
This is the Mailgun PHP *Message* utilities. 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. 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. 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. Message Builder: Allows you to build a message object by calling methods for
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. 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 Usage - Message Builder
----------------------- -----------------------
@ -95,7 +99,8 @@ Here's how to use Batch Message to easily handle batch sending jobs.
$mg = new Mailgun("key-example"); $mg = new Mailgun("key-example");
$domain = "example.com"; $domain = "example.com";
# Next, instantiate a Message Builder object from the SDK, pass in your sending domain. # Next, instantiate a Message Builder object from the SDK, pass in your sending
domain.
$batchMsg = $mg->BatchMessage($domain); $batchMsg = $mg->BatchMessage($domain);
# Define the from address. # Define the from address.
@ -110,7 +115,8 @@ $batchMsg->addToRecipient("john.doe@samples.mailgun.org", array("first" => "John
$batchMsg->addToRecipient("sally.doe@samples.mailgun.org", array("first" => "Sally", "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")); $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. // 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. // Call finalize() to send any remaining recipients still in the buffer.
$batchMsg->finalize(); $batchMsg->finalize();
@ -128,4 +134,5 @@ Available Functions (Inherits all Batch Message and Messages Functions)
More Documentation More Documentation
------------------ ------------------
See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) for more information. See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html)
for more information.