SparkPost - Addresses Associated With Bounced Email

If you are using SparkPost for email delivery, you might expect that you can determine which email addresses in a mailing list resulted in bounced messages by logging into the SparkPost website, clicking on Reports and then Bounces. But, though that will give you a total number for bounced email messages and the percentage of messages that bounced, and even the reasons email bounced, the report doesn't identify the individual email addresses that caused email to bounce. To see particular addresses that caused email to bounce, if you click on Lists, rather than Reports, and then click on Suppressions and check the check box next to Bounce Rule and click on Search, you will see recipients email addresses listed that triggered a bounced email.

SparkPost - suppressions list bounces

If you click on the SAVE AS CSV button at the bottom of the page, you can obtain a comma-separated values (CSV) file that you can view in a spreadsheet program, such as Microsoft Excel, LibreOffice Calc, or Google Sheets, or even a text editor such as Microsoft Notepad. Calc and Google Sheets are free. In the CSV file, you will see entries such as the following example:

RecipientTransactionalNon-transactional Source
tectechsupport111222@gmail.comFALSETRUE Bounce Rule

However, this list is for "hard bounces" only which are explained at Using Suppression Lists.

Hard Bounces: When messages bounce, the ISP will include a message that lets the sender know whether it was a “Soft Bounce” or a “Hard Bounce”. A “Soft Bounce” is a temporary error or delay indicating that the message was set to a valid recipient address, while a “Hard Bounce” indicates that the message was sent to an invalid email address that should not be retried. SparkPost will automatically add any email address associated with a “Hard Bounce” to your suppression list.

A hard bounce can mean there was a typo in the email address, the email address doesn't exist, or it once existed, but no longer exists.1

By automatically adding any email addresses that resulted in a "hard bounce" to your account's suppression list, SparkPost ensures that for any future email that you send to a mailing list there won't be repeated attempts to send email to a nonexistent email address, since "When a message is injected either using SMTP or HTTP, SparkPost will check the email address against the account-specific and global suppression lists. If an email address for a recipient matches an address on the list, that message will be rejected for delivery by SparkPost automatically."

You can determine if a particular email address is on the suppression list for your account through the SparkPost Application Programming Interface (API). To use the API, you can send an HTTP request to - see SparkPost API. You must include an API key you were provided in the request:

To authenticate with the APIs, specify the “Authorization” header with each request. The value of the Authorization header must be a valid API key or basic auth with the API key as username and an empty password.

To be able to access suppression list information, though, you need to add the permission "Supression Lists: Read/Write" to the API key via the following steps:

  1. While logged into your SparkPost account at the SparkPost website, click on ACCOUNT.
  2. Select API KEYS.
  3. If you wish to use your existing API key, click on the EDIT link next to it.
  4. Check the check box next to "Suppression Lists: Read/Write".

    SparkPost - API key permissions

  5. Click on the UPDATE API KEY button.

To view the status of a recipient on a Suppression List, you issue an HTTP GET command in the following format:2

GET /api/v1/suppression-list/{recipient_email} HTTP/1.1
Authorization: YOUR KEY HERE
Accept: application/json

Subsitute an actual email address for {recipient_email} and place an API key provided to you by SparkPost where you see YOUR KEY HERE . E.g.:

GET /api/v1/suppression-list/ HTTP/1.1
Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970
Accept: application/json

Note: the API key above is not an actual API key; it's merely a dummy one; you need to use your API key.

Before I added Read/Write permission for the Suppression List to my API key, I kept getting a "403 Forbidden" error message when I attempted to retrieve information for an email address on the suppression list using wget; the wget utility is available for a variety of operating systms, including Microsoft Windows. You can specify that wget use a custom header with the --header= option. It will use version 1.1 of the Hypertext Transfer Protocol (HTTP) by default.

Generic Category (English)120x600

$ wget --header="Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970" --hea
der="Accept: application/json"
--2016-09-04 12:41:48--
Resolving (,, 54
Connecting to (||:443... connecte
HTTP request sent, awaiting response... 403 Forbidden
2016-09-04 12:41:54 ERROR 403: Forbidden.


To view more details, I used the -d debugging option.

           Turn on debug output, meaning various information important to the
           developers of Wget if it does not work properly.  Your system
           administrator may have chosen to compile Wget without debug
           support, in which case -d will not work.  Please note that
           compiling with debug support is always safe---Wget compiled with
           the debug support will not print any debug info unless requested
           with -d.

With that option, I saw the following:

$ wget -d --header="Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970" --
header="Accept: application/json"
Setting --header (header) to Authorization: d12cc66a1a29755ef10fc1a1450d96dc2349
Setting --header (header) to Accept: application/json
DEBUG output created by Wget 1.14 on linux-gnu.

URI encoding = âF-8â-2016-09-04 12:45:38--
Resolving (,,
Caching =>
Connecting to (||:443... conne
Created socket 3.
Releasing 0x0000000001a42c10 (new refcount 1).
Initiating SSL handshake.
Handshake successful; connected socket 3 to SSL handle 0x0000000001a87250
  subject: /OU=GT58870261/OU=See (c)14/OU=Domain 
Control Validated - RapidSSL(R)/CN=*
  issuer:  /C=US/O=GeoTrust Inc./CN=RapidSSL SHA256 CA - G3
X509 certificate successfully verified and matches host

---request begin---
GET /api/v1/suppression-list/ HTTP/1.1
User-Agent: Wget/1.14 (linux-gnu)
Accept: application/json
Connection: Keep-Alive
Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970

---request end---
HTTP request sent, awaiting response...
---response begin---
HTTP/1.1 403 Forbidden
Cache-Control: no-cache, no-store
Content-Type: application/json
Date: Sun, 04 Sep 2016 16:45:44 GMT
Server: msys-http
Content-Length: 42
Connection: keep-alive

---response end---
403 Forbidden
Registered socket 3 for persistent reuse.
Skipping 42 bytes of body: [{"errors": [ {"message": "Forbidden."} ]}
] done.
2016-09-04 12:45:44 ERROR 403: Forbidden.


But that didn't reveal why the "403: Forbiddent" message occurred. However, once I realized I needed to update the permissions associated with the API key and added "Read/Write" permission for "Suppression Lists", I was then able to retrieve information on an email address on the suppression list. If you get a "403: Forbidden" response when attempting to retrieve information via the API check if your SparkPost plan includes the resource you are requesting and your API key has the necessary permissions.3

$ wget --header="Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970" --hea
der="Accept: application/json"
--2016-09-04 13:05:53--
Resolving (,, 54
Connecting to (||:443... connect
HTTP request sent, awaiting response... 200 OK
Length: 484 [application/json]
Saving to: ‘’
100%[======================================>] 484         --.-K/s   in 0s

2016-09-04 13:05:59 (30.7 MB/s) - ‘’ saved [484/48


The information retrieved will be stored by wget in a file with the name of the email address, e.g., in the example above.

If you attempt to retrieve information for an email address that is not on the suppression list, you will see a "404 Not Found" error message.

$ wget --header="Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970" --head
er="Accept: application/json"
--2016-09-04 13:09:20--
Resolving (,,
Connecting to (||:443... connecte
HTTP request sent, awaiting response... 404 Not Found
2016-09-04 13:09:26 ERROR 404: Not Found.

If you prefer to use the curl command or it is available and wget is not - curl is present by default on a Mac OS X system, but wget isn't - it supports custom headers using the -H option. E.g., I could use the command below to retrieve the same information as with wget.

curl -o tectechsupport1111222.txt \
-H 'Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970' \
-H 'Accept: application/json' \

Note: The backslashes permit a command to be split over multiple lines. I could also have used them with the wget command. The -o option allows you to specify an output file, in this case tectechsupport1111222.txt. - Your tech ebook super store
$ curl -o tectechsupport1111222.txt \
> -H 'Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970' \
> -H 'Accept: application/json' \
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
			 Dload  Upload   Total   Spent    Left  Speed
100   484  100   484    0     0     67      0  0:00:07  0:00:07 --:--:--   106

If you wish to delete a recipient from a Suppression List, the format for the command is as follows:

DELETE /api/v1/suppression-list/{recipient_email} HTTP/1.1
Authorization: YOUR KEY HERE
Accept: application/json

Instead of specifying the GET request method, the DELETE request method is specified, instead. E.g., to remove the email address in the example above,, I can use my API key with a curl command as shown below. I used curl rather than wget, because wget on the system I was using didn't support the --method option. Curl allows you to specify the method, e.g., DELETE, GET, PUT, with -X or --request.

$ curl -X DELETE \
> -H 'Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970' \
> -H 'Accept: application/json' \

After deleting the above entry, which at the time I issued the command was the only entry in the Suppression List, when I went to Lists then Suppressions and checked the box next to "Bounce Rule", I saw "There are no results for your current query" when I performed a search at the SparkPost website.


  1. Bounces
    Last Updated: Aug 17, 2015 04:35PM PDT
    SparkPost Support Center
  2. Using Suppression Lists
    Last Updated: Jul 21, 2016 02:10PM PDT
    SparkPost Support Center
  3. SparkPost API
    SparkPost Support Center
  4. Message Delivery: Understanding Delays and Bounces
    Last Updated: May 31, 2016 01:27PM PDT
    SparkPost Support Center

Related articles:

  1. SparkPost smart host issue with Sendmail
    Created: Saturday September 3, 2016
    MoonPoint Support


TechRabbit ad 300x250

Justdeals Daily Electronics Deals1x1 px