Using SparkPost in PHP

Jordan Nornhold
Mar. 11, 2016 by Jordan Nornhold

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.

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 packagist.org and can be installed using composer. If you’ve never used composer, check out their getting started page.

Install using the composer require command:

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.

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:

Here is another example using the Guzzle 6 adapter:

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:

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

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.

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:

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.

–Jordan

Blog-Banner-WeHeartDev_600x150-030416

5 Comments

  • How do you send to an array of recipients? using an array or object?

    $recipients[‘address’] = array(’email’=>test@test.com);
    $recipients[‘address’] = array(’email’=>test2@test2.com);

    This doesn’t seem to work when I plug it into

    ‘recipients’=>$recipients,

    Any ideas?

    Reply
  • Hi Cary,

    If you hop over to our community slack channel, our team can help you fairly quickly!

    Reply
  • Would have been cool if that was in the article or at least answered here in your comment. Now I have to ask the same. And the next one will ask again …

    Anyhow, thanks for the tutorial

  • i am new to using sparkpost and i am using spark post php api. i am doing everything in this example https://www.sparkpost.com/blog/using-sparkpost-in-php/#.V0dW7fkrLIV?knwldg=1798 , but i am getting the following error syntax error, unexpected ‘$httpAdapter’

    Reply
  • Hi Pavneet!

    If you head over to our community slack channel, someone well-versed in PHP should be able to help out!

    Reply

Share your Thoughts

Your email address will not be published.

Related Content

Running Your First Technical Workshop: The "I Have No Idea What I'm Doing" Edition

Running a technical workshop is difficult! Where do you start? How much time do you allot? What audience do you aim for? Cole talks through what he learned.

read more

Introducing Our SendGrid Template Migration Tool

Automatically migrate any SendGrid template over to SparkPost. This open source tool supports both UI- and API-driven email template migration workflows.

read more

DEVintersection: Let's Talk APIs, Swag and Mouse Ears

Get Nick Zimmerman's key takeaways from DEVintersection in Orlando and learn how you can still get your hands on some coveted Sparky socks.

read more

Start sending email in minutes!

The world’s most powerful email delivery solution is now yours in a developer-friendly, quick to set up cloud service. Open a SparkPost account today and send up to 100,000 emails per month for free.

Send 100K Emails/Month For Free

Send this to a friend