SparkPost Suppression List API
Manage the suppression list to prevent sending to unsubscribed, bounced, or complained recipients. Supports bulk insert, search, and deletion of suppressed addresses.
OpenAPI Specification
openapi: 3.0.3
info:
title: SparkPost Suppression List API
description: Manage the suppression list to prevent sending to unsubscribed, bounced, or complained recipients. Supports bulk insert, search, and deletion of suppressed addresses.
version: 1.0.0
contact:
name: SparkPost Developer Support
url: https://developers.sparkpost.com/api/suppression-list/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.sparkpost.com/api/v1
description: SparkPost Production API
security:
- ApiKeyAuth: []
paths:
/suppression-list:
put:
operationId: bulkUpsertSuppressions
summary: Bulk Create or Update Suppressions
description: Insert or update up to 10,000 suppression entries in a single request.
tags:
- Suppression List
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- recipients
properties:
recipients:
type: array
maxItems: 10000
description: List of suppression entries to create or update
items:
$ref: '#/components/schemas/SuppressionEntry'
responses:
'200':
description: Suppressions upserted
'400':
description: Invalid or malformed recipients
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
operationId: searchSuppressions
summary: Search Suppressions
description: Search the suppression list with optional filters for date range, domain, source, and type.
tags:
- Suppression List
parameters:
- name: to
in: query
required: false
description: Filter suppressions created before this date (YYYY-MM-DDTHH:mm:ssZ)
schema:
type: string
format: date-time
- name: from
in: query
required: false
description: Filter suppressions created after this date (YYYY-MM-DDTHH:mm:ssZ)
schema:
type: string
format: date-time
- name: domain
in: query
required: false
description: Filter by recipient email domain
schema:
type: string
- name: sources
in: query
required: false
description: Filter by suppression sources
schema:
type: string
- name: types
in: query
required: false
description: Filter by suppression type (transactional or non_transactional)
schema:
type: string
- name: description
in: query
required: false
description: Filter by description (partial match)
schema:
type: string
- name: description_strict
in: query
required: false
description: If true, use exact description match
schema:
type: boolean
- name: list_id
in: query
required: false
description: Filter by list ID
schema:
type: string
- name: cursor
in: query
required: false
description: Pagination cursor
schema:
type: string
- name: per_page
in: query
required: false
description: Results per page (default 1000)
schema:
type: integer
default: 1000
- name: page
in: query
required: false
description: Page number for pagination
schema:
type: integer
- name: sort
in: query
required: false
description: Sort order
schema:
type: string
enum: [asc, desc]
responses:
'200':
description: List of suppression entries
content:
application/json:
schema:
$ref: '#/components/schemas/SuppressionListResponse'
/suppression-list/summary:
get:
operationId: getSuppressionSummary
summary: Retrieve Suppression Summary
description: Retrieve suppression counts grouped by source and overall total.
tags:
- Suppression List
responses:
'200':
description: Suppression counts summary
/suppression-list/{recipient}:
put:
operationId: upsertSuppression
summary: Create or Update Single Suppression
description: Insert or update a suppression entry for a specific recipient email address.
tags:
- Suppression List
parameters:
- name: recipient
in: path
required: true
description: Recipient email address
schema:
type: string
format: email
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SingleSuppressionRequest'
responses:
'200':
description: Suppression upserted
'400':
description: Missing or invalid type
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
operationId: getSuppression
summary: Retrieve Single Suppression
description: Retrieve suppression status for a specific recipient email address.
tags:
- Suppression List
parameters:
- name: recipient
in: path
required: true
description: Recipient email address
schema:
type: string
format: email
- name: types
in: query
required: false
description: Filter by suppression type
schema:
type: string
- name: cursor
in: query
required: false
description: Pagination cursor
schema:
type: string
- name: per_page
in: query
required: false
description: Results per page (1-10,000, default 1000)
schema:
type: integer
- name: page
in: query
required: false
description: Page number
schema:
type: integer
responses:
'200':
description: Suppression entry
content:
application/json:
schema:
$ref: '#/components/schemas/SuppressionResponse'
'404':
description: Recipient not found in suppression list
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
operationId: deleteSuppression
summary: Delete Suppression
description: Remove a suppression entry for a specific recipient.
tags:
- Suppression List
parameters:
- name: recipient
in: path
required: true
description: Recipient email address
schema:
type: string
format: email
- name: list_id
in: query
required: false
description: Filter by list ID
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum: [transactional, non_transactional]
description: Suppression type to remove
responses:
'204':
description: Suppression deleted
'403':
description: Compliance-protected suppression cannot be deleted
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Recipient not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
schemas:
SuppressionEntry:
type: object
required:
- recipient
- type
properties:
recipient:
type: string
format: email
description: Recipient email address
type:
type: string
enum: [transactional, non_transactional]
description: Type of suppression
description:
type: string
description: Human-readable reason for suppression
list_id:
type: string
description: RFC 2919 compliant list identifier
SingleSuppressionRequest:
type: object
required:
- type
properties:
type:
type: string
enum: [transactional, non_transactional]
description: Type of suppression
description:
type: string
description: Human-readable reason for suppression
list_id:
type: string
description: RFC 2919 compliant list identifier
SuppressionResponse:
type: object
properties:
results:
type: array
items:
type: object
properties:
recipient:
type: string
type:
type: string
source:
type: string
description:
type: string
created:
type: string
format: date-time
updated:
type: string
format: date-time
SuppressionListResponse:
type: object
properties:
results:
type: array
items:
type: object
properties:
recipient:
type: string
type:
type: string
source:
type: string
description:
type: string
created:
type: string
format: date-time
updated:
type: string
format: date-time
total_count:
type: integer
links:
type: object
properties:
next:
type: string
ErrorResponse:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
code:
type: string
description:
type: string