Email Tools in an API World Laptop w Gears

Modern Email Tools Available To You

Email has a long heritage of standards and specifications, many of them are truly great and some are even followed. Implementing these standards requires considerable knowledge. Tools ease our work by encompassing that knowledge, packaging it up and making it available to all. One strong measure of a tool’s worth is its effectiveness at embodying knowledge and reducing cognitive load on the wielder.

The world of email tools is almost as rich as its body of standards. We have myriad services, applications, libraries and commands for configuring, testing, orchestrating and tracking our various messaging activities. The email industry is hugely advanced in the orchestration, delivery and tracking spaces, since those are where the broadest commercial interest lies. Unfortunately, tooling for email service configuration and testing is less advanced, possibly since those tools would merely improve engineers’ lives.

Suffice to say, there is still considerable knowledge required to configure, verify and troubleshoot one’s email estate.

Let’s look at a typical setup task that most email senders have grappled with: configuring DKIM signing for an email sending domain. DKIM allows you to take responsibility for the messages you send by associating your sending domain with your mail. Don’t worry too much if you don’t 100% follow all these steps. The intent is to show level of effort.

DKIM Setup: The Old School Way

Here are some outline steps we might follow to start signing our email.

  1. Generate an RSA key pair:

2. Extract just the public key:

3. Form our DKIM DNS record from public key:

4. Have our DNS provider publish the DKIM record under

5. Configure our email service to sign using your private key.

With that done, these ancillary points are left as an exercise for the reader:

DKIM Setup: The SparkPost Way

Ok, let’s try that again, this time using the SparkPost API.

  1. Ask SparkPost to create our sending domain and a matching DKIM key pair
    (we can also do this in the app):

2. Form our DKIM DNS record using API result
(Hint: SparkPost will show us the fully-formed record here):

3. Have our DNS provider publish the DKIM record

4. Verify our setup by clicking the DKIM record test button for your sending domain in SparkPost

Side note: Here are all the tasty the details on using SparkPost to manage and verify sending domains and also using the SparkPost API sending domains endpoint itself.

Much Better…

Now we’re a tiny bit biased but we do love our email API and it certainly reduces the user’s cognitive load here. Questions we no longer need to worry about:

  • What size should the RSA key be?
  • What even is an RSA key pair?
  • How do we invoke the openSSL toolkit correctly?
  • How do we handle our private key material safely?
  • How do we format our DKIM DNS record?

That single API call executes sending domain configuration, creates our DKIM keys and formats our DNS record all at once. There’s less to do, less to understand and fewer places to stub our toes along the way.

…But Not Perfect (Yet)

…and yet there are further submerged rocks to run aground on here. The DNS record could be fat fingered during publication, the DNS provider may truncate the record and what do you do if there’s an existing DKIM DNS record for your domain? How do we diagnose each of these and how do we verify the end-to-end DKIM signing and verification process?

These are all issues and questions we’ve seen in production use. Clearly, there’s more we could do, as a tool-loving developer community, to help each other be more reliably successful, faster and just plain happier in our work. Just as SparkPost has an email API, DNS services have record management APIs. Combine these with the modern web and we could build far better experiences for each other. For starters, how about:

  • A DKIM verification tool explicitly designed for diagnostic and remedial use (stay tuned for next week’s post!)
  • A modern validating SPF record editor
  • Open DMARC as a service

Against a background of modern API-driven workflows, email tooling looks a generation or so out of date. In the SaaS email infrastructure community, we can do better. Isn’t it about time for a new generation of messaging tools?

If you liked, hated, agreed, disagreed or just want to chat about email infrastructure, tooling, APIs or anything else, come join our burgeoning Slack Community. We’d love to hear from you.

—Ewan

Email Integration and Partnerships

We’ve talked a lot lately about the cool apps and integrations you can build using SparkPost. In return, some of you have showed us the cool things that you’ve built as well. And we think they’re awesome, by the way!

You're Awesome

However, we haven’t talked about our own integrations lately — the ones we hope make your job easier. Among these are Heroku, Microsoft Power BI, 250ok, and as of last week, Azure.

We’re constantly listening to you to find out what other problems we can solve for you, and our partnership program is a big part of that. So I sat down with our Senior Vice President of Business Development Joal Barbehenn last week to understand more about this essential part of SparkPost. Without further ado, grab your coffee, settle in, and let me explain.

Let me sum up.

What Do Your Partnerships and Integrations Have to Do With Me?

Firstly, Joal and I talked about our kick-ass engineering team. They love nothing more than solving your email problems and finding ways to make your life easier when it comes to programmatically sending emails through your application. That’s what they do best! Because of this, we choose to focus most of our time on our platform. We’re constantly making improvements and rolling out new features that you, the community, have asked for. This is our strong suit here at SparkPost: our email infrastructure. From deliverability to webhooks to inbound domains and our straightforward RESTful API, we’ve got that part down.

We also talked about the fact that we aren’t a front-end solution. This is where our partnerships and integrations come in — other folks who specialize in front-end logistics can provide our community with really great front-end technology to pair with our solid sending. This lets us focus on our core business, while still serving the multilayered needs of today’s sophisticated emailer (aka you) by offering full-featured campaign management and more through our partners.

A perfect example of this is 250ok. Our partnership with 250ok means that our Enterprise customers not only benefit from our email expertise, but gain insights into their email performance and brand reputation. They also have access to many other tools that maximize the value of their email programs.

As Joal says, “Through partnerships, we provide tools and integrations that help our customers achieve better results with email. We’re always looking for ways to make our technology more useful and easier to use.”

The Best is Yet to Come

We currently have several great integrations. Nonetheless, we’re always looking for the next one that will enable our service to be even more consumable, easy to use, and full-featured. Be sure to check out sparkpost.com/partners to see which integrations you could benefit from.

We want YOU wonderwoman

Have you created an integration? Leave us a note in the #lookwhatibuilt channel in the SparkPost Community Slack. We’d love to hear about it!

– Mary Thengvall

Suppression List API Updates Gears Laptop

New Suppression List API Functionality Coming Soon

At SparkPost we’re constantly using feedback from our community to enhance our application and APIs. Based on what we’ve heard, we want to let you know about some new functionality that will be coming to our suppression list API in early November 2016.

  • We’ve heard you loud and clear and will be removing rate limiting on all Suppression List API calls. We’re improving the underlying data storage for this API, which allows us to remove the rate limiting that was put in place to guard against poor performance.
  • You will now be able to retrieve your entire suppression list. Each GET call to the API will include pagination so you can page through the results.
  • You will be able to search for suppression list entries by domain or description. For example, searching for all suppressions from gmail.
  • The PUT method on a single recipient is returning. You will no longer have to do a PUT to /api/v1/suppression-list and provide an array. Instead you can now do a PUT to /api/v1/suppression-list/test@example.com to update the test@example.com resource directly.

There will be no change in functionality for the existing create, update, and delete endpoints. While we always make our best effort to prevent breaking changes, we had to make an exception and will introduce a breaking change for GET calls to the Suppression List API.

Currently, GET calls return a response where each recipient contains two fields – transactional and non_transactional:

With the updates to the API, GET calls will now return a response where a recipient will show up for each type of suppression. For example, if a recipient is suppressed for both transactional and non-transactional emails, they will show up in the list twice with transactional or non-transactional set to true.  We also added type to reflect the boolean – set to either transactional or non_transactional:

Why we are making this change

Our initial implementation has several limitations:

  • Requests to the Suppression List API are rate limited.
  • Downloading the entire suppression list is not possible as the number of records returned is capped at 100,000.
  • It is not possible to distinguish why a recipient was added to the suppression list (e.g. hard bounce or spam complaint) for recipients that were suppressed for both transactional and non-transactional emails because there is only a single entry for each recipient. This data is contained in the source field. The same can be said about the updated and description fields.
  • It is not possible to make a PUT call to update a single entry in the suppression list.
  • The Web UI is limited. It does not load an initial page of suppressions and you cannot download your list.

Currently it takes several hours for a recipient to be suppressed and we agree this isn’t a great experience. In order to support a more real-time suppression, we swapped out the backing database and changed the data model to tune it for real-time lookups. With separate entries for each recipient for each type of suppression, it allows us to support more granular suppressions by more than just transactional/non-transactional flags.

Who’s affected

This change will only impact users that have suppressed a recipient for both transactional and non-transactional messages. More specifically, have code that make GET calls to the Suppression List API and are not iterating over the entire array to check the transactional/non-transactional booleans. Although we cannot read everyone’s code that has integrated against this API, we feel pretty confident that the number of users affected are very low, if any at all.

Necessary actions

If you have code that parses the response of the GET endpoints /api/v1/suppression-list or /api/v1/suppression-list/foo@bar.com, you may have to add some additional code to iterate over your array to ensure you are parsing both the transactional and non-transactional records. If you are using subaccounts, you may already be iterating over the result but you may have to add additional logic to check for the transactional/non-transactional booleans. You can view the updated Suppression List API documentation with the improved response format here.

Making a tough decision

At SparkPost, we take backwards-compatibility very seriously. We don’t make these types of changes lightly and appreciate that our community has code in production using our API. We wanted to version the API but in this case it wouldn’t be feasible because the entire underlying architecture was changing. As a result, Taking all of the above feedback and issues into account, we believe the updates will provide a much better experience for our community in the long run.

Finally, if you’d like to discuss this update, or anything SparkPost related, please feel free to join us on our community Slack channel or reach out to us via Twitter.

—Bob Evans
Director of Application Engineering, SparkPost

sending with SMTP or API

Sending email through SparkPost to your subscribers and/or customers can be done two different ways: using our API, or sending via SMTP. The deciding factor will usually be some combination of convenience for your use case, availability/cost of coding/hardware resources, and the relative priority for your business of things like sending speed and ease of migration.

There are pros and cons for both approaches. Naturally, we think our API is pretty great, and that it has advantages over SMTP, otherwise we wouldn’t have it. Offering SMTP in addition to our API lets us support a wider range of use cases. Let’s take a look at pros and cons for both SMTP and our API, as well as examples of each approach.

Sending via SMTP with SparkPost

Sometimes SMTP is the only choice that makes sense, given your constraints. Maybe your legacy system uses SMTP, and nobody is available to write the code to send via API instead. SMTP lowers the friction for this migration path. Common steps such as modifying existing messages by adding a custom header to set the campaign for different message streams, or enabling open/click tracking tend to be significantly less effort than starting to use a new API.

Which is a nice segue to show a pro/con list for sending with SMTP:

SMTP PROS:

  1. Platform-agnostic – SMTP is accepted everywhere
    • If you want to migrate again, it’ll be easier
  2. You have full control over your “mail merge” process
    • Can generate messages however you like
    • Continue to use existing tools
  3. SMTP failures are in-band and always include context
    • Failed command and error code tell you what failed and why

SMTP CONS:

  1. SMTP is not accepted FROM everywhere
    • Some environments’ firewalls block ports commonly used for SMTP
  2. You have to build your own “mail merge” messages
    • MIME and the various email RFCs can be tricky
    • This has a resource (hardware & bandwidth) cost, especially for bulk sends
  3. SMTP is a chatty protocol
    • Each message requires several round trips to our servers
    • This adds up to longer bulk send times

Here’s an example of injecting some test content into SparkPost with SMTP, using swaks. The API key you substitute below will need the Send via SMTP permission, or authentication will fail with 535 5.7.8 Sorry. .

Sending with the SparkPost API

We like our API, and we hope you like it too. We think you should use it, as there are quite a few advantages over SMTP for many use cases, for example, triggering mail directly from your app’s server-side code. Besides, with a paid account you’re really not getting as much as you could for your money without offloading everything from your systems onto SparkPost that you can, which the API allows you to do.

API PROS:

  1. HTTP is allowed by all but the most restrictive firewalls
  2. Generation AKA “mail merge” is handled by SparkPost
    • Removes load from your servers
    • Can mean generation hardware/horsepower is no longer needed
  3. One connection round trip per API call
    • No per-message latency
  4. Async sending and concurrency is handled by SparkPost
    • Up to 10k message batches for best performance
    • Reduces complexity (AKA things to break) in your app

API CONS:

  1. Using our HTTP API means writing code
  2. Replacing in-house generation may require refactoring
    • Things like pre-processing data to format dates differently
  3. Stats are generally out-of-band
    • Some sending errors are in-band (invalid email, for example)
    • Others require processing event data one of two ways:
  4. For larger sends (10k+ recipients) batching or concurrency is recommended
    • This is a performance sweet spot, not a hard limit

Here’s an example with the same test content as above, using cURL. The API key you substitute below will need the Transmissions: Read/Write permission, or the API call will fail with HTTP/1.1 403 Forbidden, and {"errors": [ {"message": "Forbidden."} ]}  in the body.

So there you have it! As with most things in life, the answer to which will work best for you is (spoiler alert) “It depends.”. We recommend using our API, unless there are reasons that won’t work for you, such as lack of development resources to make the switch. SMTP is there as a safety net to help support those cases.

Whichever way you choose, make sure you set up DKIM! Authenticating the source and content of your email is very important, and can have a huge impact on the deliverability of your email. Instructions for setting up DKIM are here.

What were the deciding factors for your choice between SMTP and our API? Let us know on Twitter @SparkPostDev, in our Community Slack channel, or in the comments, below!

-Dave

Dev Survival Guide Blog Footer

Email Evolved Iguana Email API

An overview of the email API

With apologies to all who appreciate the particular genius of the 1967 film The Graduate, “I want to say one word to you. Just one word. Are you listening? APIs.”

These days, if you belly up to any bar (or spirits-free meet-up, if you’re so inclined) frequented by tech industry types, chances are you’re going to hear certain buzzwords. I can almost guarantee that “the cloud” and “API” are going to be among them. Sure, roll your eyes. I’ve been there, and I’ve been among those that smiled at a recent Internet meme that declared, “There is no cloud; it’s just someone else’s computer.”

But, when I really think about how tech and its use in the real world has evolved over the past decade, I stop dismissing those words as mere jargon. After all, almost every digital service I use today actually lives “in the cloud.” The bits that make up this blog actually live in the cloud, not a specific server my team maintains. So do the emails I get from readers and the music I listen to while writing. So do most of the web sites I visit and do business with. Unlike the early days of the Internet, when I first began working in this industry, server outages are all but a memory. In fact, the notion of a discrete “server” has all but been eliminated for most applications.

How did this happen? A lot of things made it possible, but the evolution of APIs are key. APIs (“application programming interfaces”) are the fundamental method by which all the virtual infrastructure embodied by the cloud is interconnected. The cloud could not exist without them. Even among business users, “API” has become a ubiquitous part of today’s technology vernacular. But, how APIs actually work, and their key role in the cloud revolution sometimes is taken for granted. We assume they just work.

A simple analogy is with the power outlets in the wall of your office or home. These receptacles provide a standardized interface to connect an appliance to the power network. Simple, right? Yes, it is. But look a little more closely, and that standard gets a little more complicated. If you have an older house, some of your outlets might not support the grounding function of three-pronged plugs or the modern, polarized version of two-prong plugs. Moreover, your electric clothes drier may require a special, oversized plug that connects to circuits that pull more power. Of course, if you’re traveling to the UK, you’ll need a special adapter to plug in your laptop, because it’s a different standard over there. Oh, heck, might as well bring the whole adapter kit with seven types of plugs to accommodate the other countries you’ll be visiting, too. And there are all kinds of extra connection standards for industrial applications that go well beyond what you or I encounter in our everyday experience.

APIs have a similar quality. They are the standard way for one piece of software to plug into—to invoke the functionality of—another piece of software. APIs connect disparate systems, services, and technologies. They are, in short, what makes the virtual infrastructure of the cloud possible. And email APIs are how any app or service can add email without reinventing the wheel.

However, APIs historically were highly idiosyncratic, with very little standardization among platforms. They were clumsy to code, difficult to invoke, and often poorly performing with limited scalability. It’s not a surprise, then that programmers and IT decision-makers alike often treated them as an afterthought to their overall technology implementation and were loathe to rely upon them in mission-critical contexts. In light of the constraints of both hardware resources and API performance, most developers chose to keep everything under one roof in a monolithic codebase optimized for a specific hardware environment.

So what changed that moved APIs from little-loved feature of monolithic applications to the all-but-invisible linchpin of the modern cloud? Three major developments are responsible for the upending of this dynamic and making today’s architecture possible:

  • The rise of the Internet as a ubiquitous web that connects nearly every computer (or other electronic devices, whether televisions, phones, refrigerators, and thermostats, inventory control systems, or factory equipment) removes one historical constraint: “always on” connectivity.
  • The exponential growth in the performance and capacity (and mirrored by plummeting costs) of computer hardware and storage devices removes another limit: economies of scale.
  • A codification (both formal and de facto) of several design patterns and best practices for describing, invoking, and transmitting information among diverse software systems provided the final piece of the puzzle: API standardization.

Together, these forces have enabled massively scaled cloud platforms. In turn, these platform-as-a-service offerings form the basis of virtualized computing stacks for countless applications across every industry and consumer market. And, yes, a good email API makes it possible to add email to nearly any app and to have some confidence that it just works.

OK, so what does that mean in the real world? Well, it means on the subway home from work, I can open my mobile app and expect to see the exact same data I touched at the office. It means the data I entered in one app get distributed to several other systems without requiring duplicate entry or manually synchronize records. It means the store I just visited doesn’t need to worry about hosting their own infrastructure just to email me a purchase receipt. It all just works, and it’s all in the cloud.

That’s pretty amazing, if you really think about it. And that’s why an email API matters.

How is your day touched by APIs and the cloud? I’d love to hear about it!

—Brent
@brentsleeper

By the way, want to learn a little more about the role of an email API and how they’ve changed the way businesses use email? Read “Email Evolved: Why the Cloud and Modern APIs Matter for the Future of Data-Driven Marketing.” And, if you’re wondering why a good email API and cloud architecture makes a difference, check out this blog post Why ESPs Struggle to Deliver Data-Driven Email. (Spoiler: it’s because ESPs aren’t really API-driven.)

Dev Survival Guide Blog Footer

This last weekend we sponsored Bitcamp, held at the University of Maryland, and in my opinion, it was one of the best hackathons we’ve ever attended!  Now would be the right time to disclose my bias: I was a Bitcamp organizer in college. So having my first experience on the other side of the sponsor booth be at my favorite hackathon, was truly special.

It was also a significant event for our Developer Advocacy team. SparkPost has sponsored small to midsized hackathons in the past, but this was our first delve into the larger student-run events, and we came prepared!

We started Friday night off by giving away tons of swag, including the limited-edition SparkPost Bitcamp stickers.

bitcamp sticker piggy pennies
SparkPost Bitcamp Stickers

These were such a hit with the hackers that we’re in the process of creating limited-edition stickers for other events! Come see us at one of our next events to get yourself one.

On Saturday, we brought in a slushy machine and served Monster Energy slushies (there was a fruit punch flavor for those who had actually slept).

slushie cups piggy pennies
Limited Edition Slushy Cups

Handing out swag and raffling off prizes is always a fun time, but what made the event really worthwhile was being able to help students with their projects. Throughout the weekend, we had six SparkPost engineers answering questions and mentoring hackers.  Nothing took me back to hackathon participant times like debugging a node.js app at 3 AM on Friday night! We even got a shout-out from one of the hackers on Twitter.

twitter piggy pennies

Whether hackers built their projects with SparkPost in mind or quickly incorporated, we got a lot of great submissions for our challenge. The deliberation was tough, but Piggy Pennies walked away as the winners of the SparkPost Challenge, with $500 in Visa gift cards. Piggy Pennies allows you to automatically round up the change of your purchases in order to save money towards a common goal with friends. The team leveraged the Capital One API (available only at hackathons) to process financial transactions, and used SparkPost Transmissions and Templates to deliver detailed updates and reports on the group’s goals. The team also implemented ways to trigger money transfers by replying to the reports using our Inbound Relay Webhooks.

bitcamp winners piggy pennies
Piggy Pennies – The Winners!

The rest of the challenge submissions were amazing too — 6 of them won major prizes from other sponsors as well. They were so cool we had to pick two honorable mentions to send to extra swag to. Contap took a new approach to the “tap phones to exchange info” concept, by automatically starting an email intro and implementing Amazon Echo Alexa reminders to contact the person. The second honorable mention was part of a surprising amount of hardware heavy submissions. Fireberry Pi used sensors and a RaspberryPi to send a warning text message including a picture of the room when gas levels were too high. This team was particularly crafty, figuring out how to use carrier email to sms gateways to send a text messages using SparkPost.

Bitcamp’s theme this year was “Explore new grounds,” and I can confidently say the SparkPost team did just that. It was a great place to meet up with such a large number of developers at varying stages of experience and skill levels. We got really valuable feedback on our product and even met a participant who had recently published a SparkPost Cake-PHP Library!. Thank you to Bitcamp for putting together such a creative atmosphere. Thank you to all the hackers, we hope to see you again soon.

Make sure to reach out to our team on Twitter or in our community Slack channel if you want to connect!

-Jose

postman

In case you missed the announcement last month, our SparkPost API documentation now comes with a “Run in Postman” button:

Untitled

What Does That Mean?

Cool! We’ve got a nifty new button. But what does that mean? And how do I know whether or not I’ll need (or want) it?
Here are the basics:

  • Are you (or one of your other developers) digging into the SparkPost API yourself, in addition to using the automated systems built around it?
  • Are you a little uncomfortable with the details of HTTP requests?
  • Do you have a hard time remembering what particular cURL command to use?

Postman to the rescue! It parses your API request and response and displays them in more manageable formats. It also simplifies the creation of API requests, which means you’re off the hook for finding the arcane syntax that will pull the precise information you’re in search of.

As Dave mentions in his blog post:

Postman gives less-technical users a way to make arbitrary HTTP requests using a point and click user interface. Collections make it easy to organize your requests and, to a point, share them. Environments make it easy to switch authentication keys and make other things configurable without editing each request.

Is your interest piqued? Good! Then without further ado, let’s dive in…

Getting Started

So what do you need to do to start using this?

Firstly, when you click this button, you’ll be directed to open this collection with your installed Postman app.

You will then see the “SparkPost API” collection show up in the left-side pane, and you can expand the various folders in the collection.

Untitled1

There are currently 76 different request types in the collection; we’ll be adding more as the API becomes even richer.

You can try running these right away – for example Message Events / Get Samples.  You’ll see results come right back in the Response window.

postman

This particular request works straight away, because just getting samples back doesn’t require authorization.

Setting up Authorization

If you try most of the other requests – such as “List All Sending Domains” – you’ll get a message saying

because each account’s data is private. You’ll need an API key set up to access this information.

postman

Here’s where a neat feature of Postman comes in. The Environments collection is set up to look for a Postman variable called {{API_KEY}}.  You can see this by viewing the request headers.

postman

If you don’t have an API key yet, you’ll want to create one.

Once you have your API key in hand, go to “Manage Environments.”

postman

Choose Add, and type a name, e.g. “My SparkPost setup.”  Then add your key and value.

Key should be just the words API_KEY  (without the curly braces this time), and the value is your specific hex string.

postman

Hit Add.  Choose “My SparkPost Setup” from your drop-down list of environments in Postman.

postman

Re-run your API request, and your authorization will be used for each of the collection’s requests without any further editing.

Here’s what I get back from “List all Sending Domains” — I can see my domain is set up and ready to go.

Untitled8

Now you’re set to explore the other requests in this collection.  Happy exploring!

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

postman and sparkpost

Run in Postman

Run SparkPost in Postman

SparkPost is an API-first service, targeting developers. What this means in practice is that we build our APIs (you guessed it) first, and then build our UI using those same API calls. We also have quite a few human users of our APIs, in addition to the automated systems we’ve built around them. Some of these users aren’t comfortable enough on the command line, or with the details of HTTP, to use cURL to build their API requests. This is where Postman comes in, turning the API request and response into something much more human-readable.

There’s a UI for That

Postman gives less-technical users a way to make arbitrary HTTP requests using a point and click user interface. Collections make it easy to organize your requests and, to a point, share them. Environments make it easy to switch authentication keys and make other things configurable without editing each request.

The new Run in Postman button makes it much easier to share collections. Since we already use Postman internally, and for demos, it was a no brainer for us to get the button set up, using examples from our API documentation.

Roll Your Own

There are lots of things you can do with the SparkPost API, and now, more easily, with Postman. For example, you could send quick, one-off test messages, or experiment with some of our more complex templating features.

When it’s time to do some data analysis, our API gives you lots of options about what kinds of metrics you’d like to see, what period of time you’d like to see data for, and how to group the data that’s returned. The examples that we’ve provided are organized by endpoint, so they’re really showing you what types of questions can be answered.

Customizing these queries so they answer the sorts of questions you have about what you’re sending is where things start to get interesting. Show us how you’re using our collection and get your questions answered on SlackTwitter or good ole’ email.

 

Blog-Banner-WeHeartDev_600x150-030416