Skip to content

docs: document open_tracking suppression type #591

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rafaelmatsumotomb wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document open_tracking suppression type #591

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 25 additions & 7 deletions content/api/suppression-list.apib
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,11 @@ Each entry indicates whether the recipient opted out of receiving one of the fol

* Transactional messages - single recipient messages that are used operationally, e.g. to reset a password or confirm a purchase.
* Non-transactional messages - used to run email campaigns where a list of recipients are targeted, e.g. advertising a sales event.
* Open tracking - recipients who revoked consent for open tracking. Unlike the sending types above, an `open_tracking` entry does **not** block sending: mail is delivered normally, but no open events are generated for the recipient (the tracking pixel itself is still served).

Suppressions can be either **account-wide** (blocking all emails of a given type) or **list-specific** (blocking emails only from a particular mailing list). Use the optional `list_id` field to create list-specific suppressions for more granular control.
Suppressions can be either **account-wide** (blocking all emails of a given type) or **list-specific** (blocking emails only from a particular mailing list). Use the optional `list_id` field to create list-specific suppressions for more granular control. `open_tracking` suppressions are always account-wide: `list_id` is not supported for that type.

Read and delete operations default to the sending types: when no `types`/`type` is provided, only `transactional` and `non_transactional` entries are returned or deleted. `open_tracking` entries are only returned or deleted when requested explicitly.


<Banner status="success">When setting up your SparkPost account, we <strong>strongly recommend</strong> you import any suppression list you have from any previous service to avoid incorrectly sending mail to unsubscribed/invalid recipients.</Banner>
Expand All @@ -36,13 +39,15 @@ By default, the search endpoint will search across the primary account's and all
+ type (enum) - Type of suppression record.
+ transactional
+ non_transactional
+ open_tracking
+ source (enum) - Source responsible for creating the list entry.
+ Spam Complaint
+ List Unsubscribe
+ Bounce Rule
+ Unsubscribe Link
+ Manually Added
+ Compliance
+ Tracking Consent Revoked
+ description (string) - Explanation for the suppression.
+ list_id (string) - Mailing list identifier for list-specific suppressions. Only returned if suppressed for a specific list. Must be RFC 2919 compliant
+ created (string) - Date suppression was created.
Expand Down Expand Up @@ -81,8 +86,9 @@ If a recipient was added by our compliance system, it cannot be updated.
+ type (enum, required) - Type of suppression record.
+ transactional
+ non_transactional
+ open_tracking
+ description (string) - Explanation for the suppression.
+ list_id (string) - Mailing list identifier for list-specific suppressions. Must be RFC 2919 compliant. Omit for account-wide suppression.
+ list_id (string) - Mailing list identifier for list-specific suppressions. Must be RFC 2919 compliant. Omit for account-wide suppression. Not supported for `open_tracking` entries.

Please note that in the unlikely scenario where your receive a HTTP 5xx level error response while bulk loading, only some of your suppression entries may have been successfully created or updated.
If this occurs, please re-submit your original request again for processing.
Expand Down Expand Up @@ -133,8 +139,9 @@ If the recipient was added by our compliance system, it cannot be updated.
+ type (enum, required) - Type of suppression record.
+ transactional
+ non_transactional
+ open_tracking
+ description (string) - Explanation for the suppression.
+ list_id (string) - Mailing list identifier for list-specific suppressions. Must be RFC 2919 compliant. Omit for account-wide suppression.
+ list_id (string) - Mailing list identifier for list-specific suppressions. Must be RFC 2919 compliant. Omit for account-wide suppression. Not supported for `open_tracking` entries.


+ Parameters
Expand Down Expand Up @@ -173,7 +180,17 @@ If the recipient was added by our compliance system, it cannot be updated.
{
"errors": [
{
"message": "Type must be one of: \'transactional\', \'non_transactional\'"
"message": "Type must be one of: \'transactional\', \'non_transactional\', \'open_tracking\'"
}
]
}

+ Response 400 (application/json)

{
"errors": [
{
"message": "list_id is not supported for type \'open_tracking\'"
}
]
}
Expand All @@ -195,7 +212,7 @@ If you don't have subaccounts, you do not need to provide the `X-MSYS-SUBACCOUNT

+ Parameters
+ recipient: `rcpt@example.com` (string, required) - Recipient email address.
+ types: `transactional` (list, optional) - Types of suppressions to match in the search, i.e. entries that are `transactional` or `non_transactional`.
+ types: `transactional` (list, optional) - Types of suppressions to match in the search, i.e. entries that are `transactional`, `non_transactional`, or `open_tracking`. If not provided, only `transactional` and `non_transactional` entries are returned; `open_tracking` entries must be requested explicitly.
+ cursor (string, optional) - The results cursor location to return, to start paging with cursor, use the value of 'initial'. When cursor is provided the `page` parameter is ignored.
+ per_page (number, optional) - Maximum number of results to return per page. Must be between 1 and 10,000.
+ Default: 1000
Expand Down Expand Up @@ -253,9 +270,10 @@ Use the `list_id` query parameter to control which suppression entries are delet


+ Data Structure
+ type (enum) - The type of suppression to delete. If not provided, the suppression will be deleted for both transactional and non-transactional.
+ type (enum) - The type of suppression to delete. If not provided, the suppression will be deleted for both transactional and non-transactional; `open_tracking` suppressions are only deleted when the type is explicitly `open_tracking`.
+ transactional
+ non_transactional
+ open_tracking


+ Parameters
Expand Down Expand Up @@ -312,7 +330,7 @@ When provided with a non-empty value, `list_id` must be RFC 2919 compliant (alph
+ from: `2017-01-01T09:00:00-0400` (string, optional) - Date the suppressions were last updated, in the format `YYYY-MM-DDTHH:mm:ssZ`.
+ domain: `example.com` (string, optional) - Domains to match in the search.
+ sources: `Bounce%20Rule,Manually%20Added` (list, optional) - Sources to match in the search, i.e. entries that were added by this source.
+ types: `transactional` (list, optional) - Types of suppressions to match in the search, i.e. entries that are `transactional` or `non_transactional`.
+ types: `transactional` (list, optional) - Types of suppressions to match in the search, i.e. entries that are `transactional`, `non_transactional`, or `open_tracking`. If not provided, only `transactional` and `non_transactional` entries are returned; `open_tracking` entries must be requested explicitly.
+ description (string, optional) - String to match in suppression descriptions.
+ description_strict (boolean, optional) - A complementary field to description. When set to true, will match the exact content in the search description, alternatively will fetch all combination of results in the description.
+ Default: false
Expand Down