Java-SparkPost Library Released!

Chris Wilson
Nov. 2, 2015 by Chris Wilson

Getting started with the SparkPost Java Client Library

SparkPost Java Client Library

At SparkPost we know many of our largest customers interface to the REST API from a Java backend. Today we are pleased to announce our Java client library. This will make developing for SparkPost a breeze for Java developers. Let’s take a look at how to get started.

Getting Started

Using java-sparkpost is as simple as including the following in your project’s pom.xml:

The version is 0.8 as of this writing. You may want to change the version to the latest version.

Sending Your First Email

To follow along check out the source code and open it in Eclipse. You can follow these instructions to help get you started. Once you have the project set up and running let’s configure the samples project:

  1. cd apps/sparkpost-samples-app
  2. Copy to
  3. Open in your favorite text editor
  4. Change SPARKPOST_API_KEY to contain your API key. Make sure to create your API key with the “Transmissions: Read/Write” permission.
  5. Enter a valid from address for the key SPARKPOST_SENDER_EMAIL. The domain should be a verified sending domain.
  6. Modify SPARKPOST_FROM with a valid from address.
  7. Enter a comma delimited list of recipients for the key SPARKPOST_RECIPIENTS.
  8. Save the file.

Once the sample project has been configured open com.sparkpost.samples.SendEmailSample in Eclipse and let’s dive into the code.

Common Sample Code

To keep the samples simple they extend a base helper class called SparkPostBaseApp, which reads in the file. The SparkPost client is configured like this:client = this.newConfiguredClient(). In your own code you will likely have your own configuration mechanism such as Spring or some other configuration system. The code is written to be easily adaptable. The base class also has some helpers to load email templates from the file systems and get the from and recipients addresses that we configured in

This is how the client is setup and how to use some of the base class helpers:

Send Email Sample

This sendEmail method takes a from address and an array of recipients:

This code is building up the transmission which describes the email campaign that is being sent. You build up your list of RecipientAttributes and populate the ‘from’ and the email on the TemplateContentAttributes object. Once configured, you use the RestConnection and ResourceTransmissions classes to send the email to the server. Once you run this sample you should see this email in your recipient’s inbox:sample_email

Login to your SparkPost account and open the Summary Report and you will see data for your email:


In my test I sent to 100 test users, so in this report there are 100 emails sent and 13 of which were opened. You can play around with to see what happens when you have bad email addresses or to test for other recipients.

Your Turn

Now it’s your turn. We can’t wait to see how you use java-sparkpost. As you explore the library here are some other samples that may help you solve your specific task:

Sample Description


Basic example of sending a local RFC822 email from local file system to a list of recipients


Example of creating a very simple email template on the server


Stores a raw RFC822 template on server


Stores an HTML template on server
ListAllSendingDomains Prints a list of domains that are configured for SparkPost account
ListAllTemplatesSample Displays the name and last updated date of templates stored on the server
ListAllTransmissionsSample Logs a list of transmission summary object

Demonstrates how to list all your webhooks


Want to Contribute?

We love pull requests for code enhancements, new samples, or better testing and documentation. Head on over to our Github repo and create an issue or pull request. We look forward to hearing from you.




  • Hi, We decided to migrate to SPP today, but there is a limitation with the java api, it doesn’t support arrays in its substitution data map, mandrill had the same issue 🙁

    Please we really need the substitution_data to support arrays, otherwise it will be impossible to migrate. Can we get some help with this?

    PS: i am still learning the java-api so i don’t dare to make a pull request yet.

  • Hi Diego!

    Our team loves feedback like this! Would you please join our community slack channel at and provide your input?


  • Diego,

    There is a branch in GitHub with better support of substitution_data. We are doing code review and testing but should be available in the Maven repo in the very near future.

    Please keep the feedback coming. Also submitting issues in GitHub is very welcome too.

    For your reference here is the branch:

    Thanks you,
    — Chris Wilson

  • Diego

    To close the loop the SparkPost Java library now support complete substitutions as requested. It is in Maven Repo or here

    — Chris Wilson

  • Really great support!

    thank you Chris!

  • Hi, I am new to sparkpost and integrating it for a startup. Do we have ability to dynamically pick a template pragmatically instead of specifying the html content in contentAttributes.setHtml(“html goes here”). I am using java for integration.

  • Hi Manish!

    I think this is what you need: contentAttributes.setTemplateId("YOUR_TEMPLATE_ID"); You need to make sure you don’t set text, html, or email_rfc822 if when using templateID. If you have other questions, please hop into our community slack at and our team would be happy to help out!

  • Thanks JENNIFER. I am able to integrate and move further. Thanks Again.

Related Content

Building an Email Archiving System: Reporting - Part 5

In the fifth installment of his blog series on building an email archive, Senior Messaging Engineer, Jeff Goldstein covers reporting.

read more

Don't Commit: A Guide to Avoiding Distractions While Coding

Manager of Software Engineering - Analytics, Robert Wenner, shares his tips and tricks for avoiding distractions while coding.

read more

View In Browser for SparkPost

Learn how to incorporate View In Browser, a link found at the top of emails that opens up the email in a browser, into emails sent via SparkPost.

read more

Get started and start sending

Try SparkPost and see how easy it is to deliver your app’s email on time and to the inbox.

Try Now

Send this to a friend