Working with an Email Recipient List
Whenever 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: