diff options
| -rw-r--r-- | README.md | 130 |
1 files changed, 99 insertions, 31 deletions
@@ -7,7 +7,7 @@ [](https://travis-ci.org/SparkPost/php-sparkpost) [](https://coveralls.io/github/SparkPost/php-sparkpost?branch=master) [](http://slack.sparkpost.com) -The official PHP library for using [the SparkPost REST API](https://developers.sparkpost.com). +The official PHP library for using [the SparkPost REST API](https://developers.sparkpost.com/api/). Before using this library, you must have a valid API Key. To get an API Key, please log in to your SparkPost account and generate one in the Settings page. @@ -48,7 +48,7 @@ use GuzzleHttp\Client; use Http\Adapter\Guzzle6\Client as GuzzleAdapter; $httpAdapter = new GuzzleAdapter(new Client()); -$sparky = new SparkPost($httpAdapter, ['key'=>'YOUR API KEY']); +$sparky = new SparkPost($httpAdapter, ['key'=>'YOUR_API_KEY']); ?> ``` @@ -101,21 +101,102 @@ $sparky = new SparkPost($httpAdapter, ['key'=>'YOUR API KEY']); * Type: `Array` * If the method is `GET` the values are encoded into the URL. Otherwise, if the method is `POST`, `PUT`, or `DELETE` the payload is used for the request body. -#### Handling Response -The request function returns a promise. You can wait for the promise or you can handle it asynchronously. +### setHttpAdapter(httpAdapter) +* `httpAdapter` + * Required: Yes + * HTTP client or adapter supported by HTTPlug + +## Endpoints +### transmissions +* **get([transmissionID] [, payload])** + * `transmissionID` - see `uri` request options + * `payload` - see request options +* **post(payload)** + * `payload` - see request options + * `payload.cc` + * Required: No + * Type: `Array` + * Recipients to recieve a carbon copy of the transmission + * `payload.bcc` + * Required: No + * Type: `Array` + * Recipients to descreetly recieve a carbon copy of the transmission +* **delete(transmissionID)** + * `transmissionID` - see `uri` request options + * `payload` - see request options -##### Wait +## Examples + +### Send An Email Using The Transmissions Endpoint +```php +<?php +use SparkPost\SparkPost; +use GuzzleHttp\Client; +use Http\Adapter\Guzzle6\Client as GuzzleAdapter; + +$httpAdapter = new GuzzleAdapter(new Client()); +$sparky = new SparkPost($httpAdapter, ['key'=>'YOUR_API_KEY']); + +$promise = $sparky->transmissions->post([ + 'content' => [ + 'from'=> [ + 'name' => 'Sparkpost Team', + 'email' => 'from@sparkpostbox.com' + ], + 'subject'=>'First Mailing From PHP', + 'html'=>'<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>', + 'text'=>'Congratulations, {{name}}!! You just sent your very first mailing!' + ], + 'substitution_data'=> ['name'=>'YOUR_FIRST_NAME'], + 'recipients'= [ + [ 'address' => '<YOUR_EMAIL_ADDRESS>' ] + ], + 'bcc' => [ + ['address' => '<ANOTHER_EMAIL_ADDRESS>' ] + ] +]); +?> +``` + +### Send An API Call Using The Base Request Function +We may not wrap every resource available in the SparkPost Client Library, for example the PHP Client Library does not wrap the Metrics resource. To allow you to use the full power of our API we created the `request` function which allows you to access the unwrapped resources. +```php +<?php +use SparkPost\SparkPost; +use GuzzleHttp\Client; +use Http\Adapter\Guzzle6\Client as GuzzleAdapter; + +$httpAdapter = new GuzzleAdapter(new Client()); +$sparky = new SparkPost($httpAdapter, ['key'=>'YOUR_API_KEY']); + +$promise = $sparky->request('GET', 'metrics/ip-pools', [ + 'from' => '2015-12-01T08:00', + 'to' => '2014-12-01T09:00', + 'timezone' => 'America/New_York', + 'limit' => '5' +]); +?> +``` + + +## Handling Responses +The all API calls return a promise. You can wait for the promise to be fulfilled or you can handle it asynchronously. + +##### Wait (Synchronous) ```php <?php try { $response = $promise->wait(); + echo $response->getStatusCode(); + echo $response->getBody(); } catch (Exception $e) { - echo $exception->getMessage(); + echo $e->getStatusCode(); + echo $e->getBody(); } ?> ``` -##### Asynchronously +##### Then (Asynchronous) ```php <?php $promise->then( @@ -125,36 +206,23 @@ $promise->then( echo $response->getBody(); }, // Failure callback - function (\Exception $e) { - echo $exception->getMessage(); + function (Exception $e) { + echo $e->getStatusCode(); + echo $e->getBody(); } ); ?> ``` -### setHttpAdapter(httpAdapter) -* `httpAdapter` - * Required: Yes - * HTTP client or adapter supported by HTTPlug +## Handling Exceptions +The promise will throw an exception if the server returns a status code of `400` or higher. + +### Exception +* **getStatusCode()** + * Returns the response status code of `400` or higher +* **getBody()** + * Returns the body of response as an `Array` -## Endpoints -### transmission -* **get([transmissionID] [, payload])** - * `transmissionID` - see `uri` request options - * `payload` - see request options -* **post(payload)** - * `payload` - see request options - * `payload.cc` - * Required: No - * Type: `Array` - * Recipients to recieve a carbon copy of the transmission - * `payload.bcc` - * Required: No - * Type: `Array` - * Recipients to descreetly recieve a carbon copy of the transmission -* **delete(transmissionID)** - * `transmissionID` - see `uri` request options - * `payload` - see request options ### Contributing See [contributing](https://github.com/SparkPost/php-sparkpost/blob/master/CONTRIBUTING.md).
\ No newline at end of file |