PHP in SparkPost

***Update: We’re so glad you’re interested in our SparkPost PHP client library. We pushed a major version change in June 2016, including a complete refactor of the library. It’s now a thin HTTP client layer with some sugar methods on the Transmission class. There is now a base resource that can be used to call any SparkPost API with a one to one mapping of payload parameters to what is listed in our API documentation. Interested in why we did this? Read more about how our client libraries came to be, and how we maintain them. For the most up to date information on our PHP Client Library, check out this article

Using SparkPost in PHP

Just guessing, but if you’re reading this, I’m willing to bet you want to use SparkPost and you probably develop in PHP. In this article, I’m going to go through some basic code so that you can get up and running using PHP and SparkPost.

The SparkPost PHP Client Library

The good news is we have a client library to help you out. It does have a few pre-requisites, but we’ve tried to design the library to be as flexible as possible.

The library requires:

  • PHP 5.5
  • Some sort of request library. This can be cURL or some other library like Guzzle.

Installing & Setup

The SparkPost client library is hosted on and can be installed using composer. If you’ve never used composer, check out their getting started page.

Install using the `composer require` command:

composer require sparkpost/php-sparkpost

Cool.  Now that that is taken care of, we should be good to go and can start using SparkPost in code.  Just like using any other composer package, the first step is to require the autoloader and then we can use the SparkPost class.

require ‘vendor/autoload.php’;
use SparkPost\SparkPost;

Now, like I said above in the requirements you have to have some sort of request library or utility available.  This can be cURL or something more like Guzzle. Its really up to you and what is available in your environment. SparkPost currently implements the egeloen/ivory-http-adapter and you can see all of the supported request adapters on their github page. (See sidenote below). You’ll have to implement one of these adapters and pass it into the SparkPost constructor. The second argument is your SparkPost API key.

Here is an example using the cURL adapter:

use SparkPost\SparkPost;
use Ivory\HttpAdapter\CurlHttpAdapter;
$httpAdapter = new CurlHttpAdapter();
$sparky = new SparkPost($httpAdapter, ‘YOUR API KEY’);

Here is another example using the Guzzle 6 adapter:

use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Ivory\HttpAdapter\Guzzle6HttpAdapter;
$httpAdapter = new Guzzle6HttpAdapter(new Client());
$sparky = new SparkPost($httpAdapter, ’YOUR API KEY’);

Sidenote on the egeloen/ivory-http-adapter

This library is currently deprecated in favor of php-http/httplug library.  We use Ivory internally to make it simple for you to use whatever HTTP library you want. We do plan to move to the new library in version 2 of the SparkPost PHP Library.

Sending Email

Now that everything is setup, sending your first email is easy. The function you need to know is `transmission->send` and it takes an associative array with a configuration of the email that you want to send. Some of the more important properties of the config are from, html, text, subject, and recipients, but a full list can be found on the SparkPost PHP Library’s GitHub page.

Here is a simple example:

$results = $sparky->transmission->send([
    'from'=>'From Envelope <>',
    'html'=>'<p>Hello World!</p>',
    'text'=>'Hello World!',
    'subject'=>'Example Email',
          'name'=>'John Doe'

A more advanced example can include things like substitution data based on each recipient:

$results = $sparky->transmission->send([
    'from'=>'The Great Day Squad <>',
    'html'=>'<p>Hi {{ preferred_name }}! Hope you’re having a great day!</p>',
    'text'=>'Hi {{ preferred_name }}! Hope you’re having a great day!',
    'subject'=>'Have a great day!',
          'name'=>'John Andrew Doe'

Error Handling

If there are any issues performing any operation, the SparkPost library will throw an exception. So in practice, it is a good idea to wrap this send statement in a try-catch block to handle the error properly.

try {
 $results = $sparky->transmission->send($emailConfig);
} catch (\Exception $error) {
 // handle error

Other Capabilities

Under the hood, the SparkPost client library is just a helper library around our REST APIs.  We are constantly coming out with new APIs with new functionality, and we thought it would be a great idea if you could use the client library with those new APIs as they are released without having to wait for an update.  Thats why we created the `setupUnwrapped` function. With it, you can use the client library with any of our APIs and use one of four functions to access our REST APIs. Heres how it works in an example getting deliverability metrics:

$results = $sparky->metrics->get('deliverability', [

In the code above, the ‘setupUnwrapped’ function creates a helper for the metrics API and adds it to the ‘$sparky’ instance as a property. This new property has four main functions: get, create, update, and delete.  You can use these functions to access our REST API endpoints which determined by the first parameter.  The second parameter is either an array that maps to a query string like the example above, or an array that gets json encoded as the post body depending on which method you choose.  ‘$results’ will contain the API response.  The good news is that this method works even if we choose to add support for the same endpoint in the future. So you don’t have to worry about breaking code when you update.  Since this method of “build your own helper” relies on directly utilizing the our REST APIs, you should familiarize yourself with our API documentation when using it.

For more information please checkout the SparkPost PHP Library on GitHub, our developer hub, or come talk to our team in our community Slack.


Dev Survival Guide Blog Footer