Sign up for a SparkPost account and visit our Developer Hub for even more content.
The official PHP library for using the SparkPost REST 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.
Please note: The composer package sparkpost/php-sparkpost
has been changed to sparkpost/sparkpost
starting with version 2.0.
The recommended way to install the SparkPost PHP Library is through composer.
# Install Composer
curl -sS https://getcomposer.org/installer | php
Sparkpost requires php-http client (see Setting up a Request Adapter). There are several providers available. If you were using guzzle6 your install might look like this.
composer require guzzlehttp/guzzle
composer require php-http/guzzle6-adapter
Next, run the Composer command to install the SparkPost PHP Library:
composer require sparkpost/sparkpost
After installing, you need to require Composer's autoloader:
require 'vendor/autoload.php';
use SparkPost\SparkPost;
Note: Without composer the costs outweight the benefits of using the PHP client library. A simple function like the one in issue #164 wraps the SparkPost API and makes it easy to use the API without resolving the composer dependencies.
Because of dependency collision, we have opted to use a request adapter rather than requiring a request library. This means that your application will need to pass in a request adapter to the constructor of the SparkPost Library. We use the HTTPlug in SparkPost. Please visit their repo for a list of supported clients and adapters. If you don't currently use a request library, you will need to require one and create a client from it and pass it along. The example below uses the GuzzleHttp Client Library.
A Client can be setup like so:
<?php
require 'vendor/autoload.php';
use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
$httpClient = new GuzzleAdapter(new Client());
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
?>
httpClient
- Required: Yes
- HTTP client or adapter supported by HTTPlug
options
- Required: Yes
- Type:
String
orArray
- A valid Sparkpost API key or an array of options
options.key
- Required: Yes
- Type:
String
- A valid Sparkpost API key
options.host
- Required: No
- Type:
String
- Default:
api.sparkpost.com
options.protocol
- Required: No
- Type:
String
- Default:
https
options.port
- Required: No
- Type:
Number
- Default: 443
options.version
- Required: No
- Type:
String
- Default:
v1
options.async
- Required: No
- Type:
Boolean
- Default:
true
async
defines if therequest
function sends an asynchronous or synchronous request. If your client does not support async requests set this tofalse
options.retries
- Required: No
- Type:
Number
- Default:
0
retries
controls how many API call attempts the client makes after receiving a 5xx response
options.debug
- Required: No
- Type:
Boolean
- Default:
false
- If
debug
is true, then allSparkPostResponse
andSparkPostException
instances will return any array of the request values through the functiongetRequest
method
- Required: Yes
- Type:
String
- HTTP method for request
uri
- Required: Yes
- Type:
String
- The URI to recieve the request
payload
- Required: No
- Type:
Array
- If the method is
GET
the values are encoded into the URL. Otherwise, if the method isPOST
,PUT
, orDELETE
the payload is used for the request body.
headers
- Required: No
- Type:
Array
- Custom headers to be sent with the request.
Sends a synchronous request to the SparkPost API and returns a SparkPostResponse
Sends an asynchronous request to the SparkPost API and returns a SparkPostPromise
httpClient
- Required: Yes
- HTTP client or adapter supported by HTTPlug
options
- Required: Yes
- Type:
Array
- See constructor
- get([transmissionID] [, payload])
transmissionID
- seeuri
request optionspayload
- see request options
- post(payload)
payload
- see request optionspayload.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
- seeuri
request options
<?php
require 'vendor/autoload.php';
use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
$httpClient = new GuzzleAdapter(new Client());
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
$promise = $sparky->transmissions->post([
'content' => [
'from' => [
'name' => 'SparkPost Team',
'email' => '[email protected]',
],
'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' => [
'name' => 'YOUR_NAME',
'email' => 'YOUR_EMAIL',
],
],
],
'cc' => [
[
'address' => [
'name' => 'ANOTHER_NAME',
'email' => 'ANOTHER_EMAIL',
],
],
],
'bcc' => [
[
'address' => [
'name' => 'AND_ANOTHER_NAME',
'email' => 'AND_ANOTHER_EMAIL',
],
],
],
]);
?>
We provide a base request function to access any of our API resources.
<?php
require 'vendor/autoload.php';
use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
$httpClient = new GuzzleAdapter(new Client());
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
$promise = $sparky->request('GET', 'metrics/ip-pools', [
'from' => '2014-12-01T09:00',
'to' => '2015-12-01T08:00',
'timezone' => 'America/New_York',
'limit' => '5',
]);
?>
The API calls either return a SparkPostPromise
or SparkPostResponse
depending on if async
is true
or false
$sparky->setOptions(['async' => false]);
try {
$response = $sparky->transmissions->get();
echo $response->getStatusCode()."\n";
print_r($response->getBody())."\n";
}
catch (\Exception $e) {
echo $e->getCode()."\n";
echo $e->getMessage()."\n";
}
Asynchronous an be handled in two ways: by passing callbacks or waiting for the promise to be fulfilled. Waiting acts like synchronous request.
$promise = $sparky->transmissions->get();
try {
$response = $promise->wait();
echo $response->getStatusCode()."\n";
print_r($response->getBody())."\n";
} catch (\Exception $e) {
echo $e->getCode()."\n";
echo $e->getMessage()."\n";
}
echo "I will print out after the promise is fulfilled";
$promise = $sparky->transmissions->get();
$promise->then(
// Success callback
function ($response) {
echo $response->getStatusCode()."\n";
print_r($response->getBody())."\n";
},
// Failure callback
function (Exception $e) {
echo $e->getCode()."\n";
echo $e->getMessage()."\n";
}
);
echo "I will print out before the promise is fulfilled";
// You can combine multiple promises using \GuzzleHttp\Promise\all() and other functions from the library.
$promise->wait();
An exception will be thrown in two cases: there is a problem with the request or the server returns a status code of 400
or higher.
- getCode()
- Returns the response status code of
400
or higher
- Returns the response status code of
- getMessage()
- Returns the exception message
- getBody()
- If there is a response body it returns it as an
Array
. Otherwise it returnsnull
.
- If there is a response body it returns it as an
- getRequest()
- Returns an array with the request values
method
,url
,headers
,body
whendebug
istrue
- Returns an array with the request values
See contributing.