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

Dev Survival Guide Blog Footer

7 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
  • how can I send an email to the whole list?

    Reply
  • Hi Adnan,

    For the 1.x version you can take a look at this example. If you are using the 2.x version you can follow this example

    If you have any other questions, don’t forget you can chat with us directly on Slack

    Thanks!
    Holly

    Reply

Share your Thoughts

Your email address will not be published.

Related Content

How to Design a Better Onboarding Experience

Onboarding is tough to get right. Here’s how we improved our onboarding experience and why it'll make our users and developer community more successful.

read more

The Sticking Power Of The SparkPost Flame

Wondering about the SparkPost stickers? Here’s the backstory on our brilliant designer, the challenges we’ve faced, and the fun we’ve had along the way.

read more

Event Data Made Easy with SparkPost Message Events

Did you know that SparkPost also supports a “pull” model Message Events API that enables you to download your event data for up to ten days afterwards?

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!

Send 100K Emails/Month For Free

Send this to a friend