Managing the email suppression list via API

Overview

The email suppression list stores contact email addresses that are considered suppressed, meaning email messages cannot be sent to the listed addresses. You can manage the email suppression list in-app or via API. In this article, you’ll find the relevant API endpoints to manage the list via API

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

HTTP method and request resource

Get the emails on the suppression list


 POST https://api.ap3api.com/v1/suppression-list/email/get

Add emails to the suppression list


 PUT https://api.ap3api.com/v1/suppression-list/email/add

Remove from suppression list


 PUT https://api.ap3api.com/v1/suppression-list/email/remove

TIP: Refer to the request body section to learn how to format the body of your API requests for each method.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

X-Api-Key: CUSTOM-PRIVATE-API-KEY
Content-Type: application/json

Request body

The request body consists of a JSON object whose valid elements are listed in the table below.

Example get request body

json
 { 

"limit": 5, 
"offset": 0, 
"sort_order": "desc", 
"sort": "email" 

}

Example add request body

json
 { 

"emails": ["example@example.com", "example2@example.com"] 

}

Example remove request body

json
 { 

"emails": ["example@example.com", "example2@example.com"] 

}

Valid request body elements

The following table lists all valid request body elements which are available to these endpoints.

Element	Type	Description
`limit`	`integer` between `1` to `500` (default value is `50`)	The `limit` element value determines the number of emails to be returned by Ortto from the request. This value also represents the "page" length of emails (for pagination purposes), since potentially many thousands of email records could be retrieved from a single request. This element can be used in conjunction with `offset` to retrieve subsequent pages of people records. If this `limit` element is not specified in the request, or an integer value beyond the permitted maximum is specified, then this value is assumed to be `50`.
`offset`	`integer` with a default value of `0`	The `offset` element represents the count of email records in the suppression list for pagination purposes, and is the point from which the next page of records (defined by the `limit` m) is retrieved.
`sort_order`	`string` with value `asc` or `desc` (default value is `desc`)	The `sort_order` element determines the order in which the people returned are sorted, based on the `sort` element. Specifying this `sort_order` member is only relevant when the `sort` element is also specified.
`sort`	`string`	The `sort` element is used to specify the person field used to sort the people returned from your Ortto account’s CDP.
`emails`	`array` of `string` values	The `emails` array contains the email addresses to be added to or removed from the suppression list.

Response payload elements

The following table lists all elements in the response from a request to this endpoint. Only the GET request will include these elements in the response.

Element	Description
`email`	The email address of the record in the suppression list.
`created_at`	The date and time when the email was added to the suppression list.
`reason_text`	The reason the email was added to the suppression list. Learn more about possible reasons here.