How to Create, Delete, Retrieve and Update an Email Recipient List in SparkPost

Aydrian Howard
Jul. 8, 2015 by Aydrian Howard

Working with an Email Recipient List

CreateRetrieveDeleteWhenever you’re sending bulk email, or even email to more than a handful of recipients, it’s best to put them in an email recipient list. This is particularly true if you plan to send multiple emails to the same recipients. Otherwise, you’ll have to reference every recipient every time you send an email, and the packet will be large. You can avoid these issues by referencing a recipient list. You can create, retrieve, update and delete recipient lists using the SparkPost API.

A recipient list is a collection of recipients that can be used in a transmission. The Recipient List API allows you to manage these lists. When creating a new transmission, you can submit recipients “inline” as part of the transmission data or specify a stored recipient list ID attribute instead.

When working with recipient lists, you have flexibility in deciding who does what. One person can be in charge of everything (using one API key) or you can implement separation of duties by having multiple API keys. One person can be responsible for creating recipient lists, someone else can be responsible for creating the templates and yet a third person can be responsible for creating transmissions. Each person simply needs his or her own API key with the appropriate permissions. This way, you have three different people working together but separately, and you can marry those functions together whenever you create a transmission.

You can also use the SparkPost API to retrieve a list of all the available recipient lists in an account. This allows you to see a summary of all recipient lists.

You can update an existing recipient list, but it will completely replace the existing list. If you would like to append to a list, we recommend retrieving the existing list, modifying the recipients, and then performing an update.

You can permanently delete a recipient list, but once it’s deleted, it cannot be recovered, so we advise you to keep a backup copy and double-check that you won’t be using it again. If you do need to send to a list that was deleted, you will need to resubmit the list using the Create API call. This is often not a problem because many people use a marketing platform for list maintenance and then use SparkPost for email transmission through our SMTP servers. (To understand how to use SparkPost as an SMTP relay, see this video tutorial)

The Recipient List API operates on lists as a whole and does not currently support management of individual recipients. I’ve made some training videos that explain, step-by-step, how to create, retrieve and delete recipient lists. We’ve also just added a new feature on how to update recipient lists and the tutorial is below:

Related Content

Meet Our New West Coast Developer Advocate

From Intern to Engineer to West Coast Developer Advocate -- Avi’s got big things ahead of him! Learn more about his journey and what he's most excited about.

read more

Community Spotlight: Rise And Shine With This Alexa Skill

Getting out of bed in the morning is easier with coffee and your new favorite Alexa skill: MyMorning.Online, our winners from the recent AngelHack.

read more

Our Top 5 Email Template Hacks

From creating standards that can apply to many templates to design hints on validating your data, here are our top 5 email template hacks.

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!

Get Started

Send this to a friend