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:
| Recipient | Transactional | Non-transactional | Source |
| tectechsupport111222@gmail.com | FALSE | TRUE | 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 https://api.sparkpost.com/api/v1 - 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:
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/tectechsupport111222@gmail.com 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.
$ wget https://api.sparkpost.com/api/v1/suppression-list/tectechsupport111222@gm ail.com --header="Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970" --hea der="Accept: application/json" --2016-09-04 12:41:48-- https://api.sparkpost.com/api/v1/suppression-list/tecte chsupport111222@gmail.com Resolving api.sparkpost.com (api.sparkpost.com)... 54.69.65.44, 52.40.18.107, 54 .191.102.120 Connecting to api.sparkpost.com (api.sparkpost.com)|54.69.65.44|:443... connecte d. 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.
-d
--debug
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 https://api.sparkpost.com/api/v1/suppression-list/tectechsupport111222
@gmail.com --header="Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970" --
header="Accept: application/json"
Setting --header (header) to Authorization: d12cc66a1a29755ef10fc1a1450d96dc2349
5970
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-- https://api.sparkpost.com/api/v1/sup
pression-list/tectechsupport111222@gmail.com
Resolving api.sparkpost.com (api.sparkpost.com)... 54.191.102.120, 52.40.18.107,
54.69.65.44
Caching api.sparkpost.com => 54.191.102.120 52.40.18.107 54.69.65.44
Connecting to api.sparkpost.com (api.sparkpost.com)|54.191.102.120|:443... conne
cted.
Created socket 3.
Releasing 0x0000000001a42c10 (new refcount 1).
Initiating SSL handshake.
Handshake successful; connected socket 3 to SSL handle 0x0000000001a87250
certificate:
subject: /OU=GT58870261/OU=See www.rapidssl.com/resources/cps (c)14/OU=Domain
Control Validated - RapidSSL(R)/CN=*.sparkpost.com
issuer: /C=US/O=GeoTrust Inc./CN=RapidSSL SHA256 CA - G3
X509 certificate successfully verified and matches host api.sparkpost.com
---request begin---
GET /api/v1/suppression-list/tectechsupport111222@gmail.com HTTP/1.1
User-Agent: Wget/1.14 (linux-gnu)
Accept: application/json
Host: api.sparkpost.com
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 https://api.sparkpost.com/api/v1/suppression-list/tectechsupport111222@gm ail.com --header="Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970" --hea der="Accept: application/json" --2016-09-04 13:05:53-- https://api.sparkpost.com/api/v1/suppression-list/tecte chsupport111222@gmail.com Resolving api.sparkpost.com (api.sparkpost.com)... 52.40.18.107, 54.69.65.44, 54 .191.102.120 Connecting to api.sparkpost.com (api.sparkpost.com)|52.40.18.107|:443... connect ed. HTTP request sent, awaiting response... 200 OK Length: 484 [application/json] Saving to: ‘tectechsupport111222@gmail.com’ 100%[======================================>] 484 --.-K/s in 0s 2016-09-04 13:05:59 (30.7 MB/s) - ‘tectechsupport111222@gmail.com’ saved [484/48 4] $
The information retrieved will be stored by wget in a file with the name of the email address, e.g., tectechsupport111222@gmail.com 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 https://api.sparkpost.com/api/v1/suppression-list/someotheracct111223@gma il.com --header="Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970" --head er="Accept: application/json" --2016-09-04 13:09:20-- https://api.sparkpost.com/api/v1/suppression-list/someo theracct111223@gmail.com Resolving api.sparkpost.com (api.sparkpost.com)... 54.69.65.44, 54.191.102.120, 52.40.18.107 Connecting to api.sparkpost.com (api.sparkpost.com)|54.69.65.44|:443... connecte d. 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' \
https://api.sparkpost.com/api/v1/suppression-list/tectechsupport111222@gmail.com
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.
$ curl -o tectechsupport1111222.txt \ > -H 'Authorization: d12cc66a1a29755ef10fc1a1450d96dc23495970' \ > -H 'Accept: application/json' \ > https://api.sparkpost.com/api/v1/suppression-list/tectechsupport111222@gmail.com % 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,
tectechsupport111222@gmail.com, 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' \ > https://api.sparkpost.com/api/v1/suppression-list/tectechsupport111222@gmail.com $
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.
References:
Related articles: