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 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

cascading dataEffective email is fueled by data-driven, personalized content containing a clear and conspicuous purpose. This is true both for transactional email and for non-transactional (marketing, one-to-many, or ‘bulk’) email. As email content providers, when we deliver anticipated, well-organized, concise and personalized email transmissions to our recipients, the more relevant, engaging and compelling our email content will be. SparkPost’s REST API easily empowers you as a developer to programmatically generate relevant, personalized content for all of your transmissions with our Substitution Data templating. SparkPost’s Substitution Data allows you to data-power your email transmission content at appropriate scopes within the email assembly process.  Data-driven customer content in your email transmissions strengthens your messaging and makes it more insightful and friendly. Read about all of the logic, looping, conditional statements and other programmatic power in our Substitution Data Reference.

Unique to SparkPost (versus our competitors), we enable cascading substitutions at the transmission level, the template level, and the recipient level for maximum customization. The availability of data dictates how the customization happens.

Similar to cascading style sheets (CSS) which style DOM elements using cascading rule importance, SparkPost gives you the same degree of flexibility in applying data-driven personalization to your emails. We can think of the cascade as tiers that get closer and closer to the individual recipient.

If you have substitution data for the recipient (shown below as {{Salutory}}, that takes precedence. But if you don’t have substitution data at that level, SparkPost looks for substitution data at the template level and lastly at the transmission level. For example, you might have designed the template for people who bought a certain product. In that case, you could say “Thank you for buying our new gizmo!” If no substitution data is available at the template level, it falls back to what you may have defined at the transmission level (in the example below, “Greetings and salutations, Valued Customer”).

The cascading approach to Substitution Data provides a high level of flexibility so that email is as personalized as possible based on the data you have available for each recipient. Substitution is a powerful feature. For an in-depth look at Substitution Data, see the reference doc at https://www.sparkpost.com/api#/reference/substitutions-reference

To learn more: