From 69361929c0c673b955dd54e776ab27a934808da4 Mon Sep 17 00:00:00 2001 From: Rafael Matsumoto <110425783+rafaelmatsumotomb@users.noreply.github.com> Date: Wed, 26 Aug 2026 14:15:40 -0300 Subject: [PATCH] docs-suppression-open-tracking: docs: document open_tracking suppression type Co-Authored-By: Claude Fable 5 --- content/api/suppression-list.apib | 32 ++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/content/api/suppression-list.apib b/content/api/suppression-list.apib index 340648b1..6bc4d360 100644 --- a/content/api/suppression-list.apib +++ b/content/api/suppression-list.apib @@ -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. When setting up your SparkPost account, we strongly recommend you import any suppression list you have from any previous service to avoid incorrectly sending mail to unsubscribed/invalid recipients. @@ -36,6 +39,7 @@ 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 @@ -43,6 +47,7 @@ By default, the search endpoint will search across the primary account's and all + 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. @@ -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. @@ -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 @@ -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\'" } ] } @@ -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 @@ -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 @@ -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