Using The SparkPost Heroku Add-On

August 3, 2018 Contributors

The SparkPost add-on in Heroku provides developers an easily accessible application to leverage for email delivery.

SparkPost is available via a modern RESTful API and has supported client libraries for Node.js, Python, PHP, Java, Go, and Elixir as well as documented examples in all those languages plus Swift, Objective-C and VB.


If you’re in a hurry, here’s a video tutorial to get you up and running quickly:

Provisioning The Add-On

SparkPost can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

The following settings are available in the app configuration:

Config Setting Description
SPARKPOST_API_KEY The API key for the SparkPost API
SPARKPOST_API_URL The base URI for the SparkPost API

After installing SparkPost the application should be configured to fully integrate with the add-on.

In order to use the API key, it’s necessary to accept the terms of use via the SparkPost dashboard.

SparkPost is setup with a sandbox domain which can be used to send up to 5 messages. To send more messages, create a sending domain via the SparkPost dashboard or the API.

Local Setup

Environment Setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command for each value that you want to add to your .env file.

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

For more information, see the Heroku Local article.

Using The API

SparkPost is available via API and has supported SDKs for Node.js, Python, and PHP. The SparkPost API enables client applications to integrate with SparkPost and perform actions associated with account management, message generation, and reporting. More information can be found

Using With Node.js

SparkPost has a Node SDK for your favorite SparkPost APIs. The module source can be found onGithub.

The following code shows an example of including the SparkPost module and sending a transmission.

Using With Python

SparkPost has an official Python module. The module source can be found on GitHub.

To use, install from PyPI using pip:

The following code shows an example of including the SparkPost module and sending a transmission.

Using With PHP

SparkPost has an official PHP SDK. The module source can be found on GitHub.

The recommended way to install the SparkPost PHP SDK is through composer.

Next, run the Composer command to install the SparkPost PHP SDK:

After installing, you need to require Composer’s autoloader:

The following code shows an example of including the SparkPost module and sending a transmission:


For more information on the features available within the SparkPost dashboard please see the docs at

The SparkPost dashboard allows you to view metrics and create sending domains and templates.

The dashboard can be accessed via the CLI:$ heroku addons:open sparkpost Opening sparkpost for sharp-mountain-4005or by visiting the Heroku Dashboard and selecting the application in question. Select SparkPost from the Add-ons menu.

Migrating Between Plans

Use the heroku addons:upgrade command to migrate to a new plan.

Sending may be disabled for up to 24 hours if a user downgrades to a plan and has exceeded the hourly or daily limit for the new plan. The request is denied if a user tries to downgrade to a new plan whose monthly limit is less than their current monthly usage.

Removing The Add-On

SparkPost can be removed via the CLI. The account will be suspended and sending will be disabled for your API key.


All SparkPost support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at [email protected].