Add records to a suppression list

POST

/v1/suppression-lists/{suppressionListId}/records

const url = 'https://api.postlever.com/v1/suppression-lists/497f6eca-6276-4993-bfeb-53cbbbba6f08/records';
const options = {
  method: 'POST',
  headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'},
  body: '{"records":["test@email.com","other@email.com"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.postlever.com/v1/suppression-lists/497f6eca-6276-4993-bfeb-53cbbbba6f08/records \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "records": [ "test@email.com", "other@email.com" ] }'

Adds records to one of your suppression lists. A single request accepts up to 1000 records.

Each record must match the list’s format: an email address for a plain text list, an MD5 hex digest for an md5 list, or a SHA-512 hex digest for a sha512 list. Values are trimmed and lowercased before they are stored.

If any record does not match the format, the request is rejected with 400 invalid_request_error and no records are added. detail gives the zero-based indexes of the records that failed, and errors points at the first of them.

Records already on the list are counted in duplicateCount instead of being added again, so sending the same batch twice is safe. Records repeated within a single request are counted the same way.

Every request is recorded in the list’s import history, alongside manual uploads. A list takes one import at a time, so a request made while a file upload or another add-records request is still running is rejected with 409 operation_in_progress.

Authorizations

postlever_api_key

Parameters

Path Parameters

suppressionListId

required

string format: uuid

The id of the suppression list.

Request Body^required

application/json

object

records

required

The records to add. Each entry must match the suppression list’s format: an email address for a plain text list, an MD5 hex digest for an md5 list, or a SHA-512 hex digest for a sha512 list. Entries must be unique within the request.

Array<string>

>= 1 items <= 1000 items unique items

Responses

201

A count of the records added and the records already present.

application/json

object

importId

required

The id of the import recorded for this request, as it appears in the list’s import history.

string format: uuid

totalCount

required

The number of records in the request.

integer

addedCount

required

The number of records added to the list.

integer

duplicateCount

required

The number of records that were already on the list, or repeated within the request. addedCount plus duplicateCount always equals totalCount.

integer

Example

{
  "importId": "8f14e45f-ea8f-4b1a-9c2d-2b0a5a1f3c7e",
  "totalCount": 2,
  "addedCount": 1,
  "duplicateCount": 1
}

400

A record does not match the list’s format, or the request body fails validation.

application/json

Error envelope returned by every v1 endpoint for failures, following RFC 9457 Problem Details with code and errors extensions.

object

type

required

URI identifying the problem type; dereferences to its documentation.

string format: uri

status

required

HTTP status code applicable to this problem.

integer

title

required

Short, human-readable summary of the problem type.

string

detail

required

Detailed explanation specific to this occurrence.

string

code

required

Error code identifying the specific error condition.

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error api_error contact_exists operation_in_progress

instance

URI reference identifying this specific occurrence (the request URI).

string format: uri-reference

errors

Provides additional information when the error relates to specific request fields.

Array<object>

object

detail

required

Detailed explanation for this specific field error.

string

pointer

JSON Pointer (RFC 6901) to the request body value that caused the error (e.g. /email, /attributes/firstName).

string

parameter

The URI query parameter that caused the error (e.g. pageSize, name[invalid]).

string

Examples

A record does not match the list's format

{
  "type": "https://docs.postlever.com/error-codes#invalid_request_error",
  "status": 400,
  "title": "Invalid request",
  "detail": "Expected every record to be a valid email address (list format: plain text). Invalid at index(es): 2",
  "code": "invalid_request_error",
  "instance": "/v1/suppression-lists/497f6eca-6276-4993-bfeb-53cbbbba6f08/records",
  "errors": [
    {
      "detail": "Expected every record to be a valid email address (list format: plain text). Invalid at index(es): 2",
      "pointer": "/records/2"
    }
  ]
}

The request contains more than 1000 records

{
  "type": "https://docs.postlever.com/error-codes#invalid_request_error",
  "status": 400,
  "title": "Invalid request",
  "detail": "records must contain no more than 1000 elements",
  "code": "invalid_request_error",
  "instance": "/v1/suppression-lists/497f6eca-6276-4993-bfeb-53cbbbba6f08/records",
  "errors": [
    {
      "detail": "records must contain no more than 1000 elements"
    }
  ]
}

401

Missing or invalid API key.

application/json

Error envelope returned by every v1 endpoint for failures, following RFC 9457 Problem Details with code and errors extensions.

object

type

required

URI identifying the problem type; dereferences to its documentation.

string format: uri

status

required

HTTP status code applicable to this problem.

integer

title

required

Short, human-readable summary of the problem type.

string

detail

required

Detailed explanation specific to this occurrence.

string

code

required

Error code identifying the specific error condition.

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error api_error contact_exists operation_in_progress

instance

URI reference identifying this specific occurrence (the request URI).

string format: uri-reference

errors

Provides additional information when the error relates to specific request fields.

Array<object>

object

detail

required

Detailed explanation for this specific field error.

string

pointer

JSON Pointer (RFC 6901) to the request body value that caused the error (e.g. /email, /attributes/firstName).

string

parameter

The URI query parameter that caused the error (e.g. pageSize, name[invalid]).

string

Example

{
  "type": "https://docs.postlever.com/error-codes#authentication_error",
  "status": 401,
  "title": "Authentication failed",
  "detail": "Missing or invalid API key",
  "code": "authentication_error",
  "instance": "/v1/contacts"
}

403

Permission denied.

application/json

Error envelope returned by every v1 endpoint for failures, following RFC 9457 Problem Details with code and errors extensions.

object

type

required

URI identifying the problem type; dereferences to its documentation.

string format: uri

status

required

HTTP status code applicable to this problem.

integer

title

required

Short, human-readable summary of the problem type.

string

detail

required

Detailed explanation specific to this occurrence.

string

code

required

Error code identifying the specific error condition.

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error api_error contact_exists operation_in_progress

instance

URI reference identifying this specific occurrence (the request URI).

string format: uri-reference

errors

Provides additional information when the error relates to specific request fields.

Array<object>

object

detail

required

Detailed explanation for this specific field error.

string

pointer

JSON Pointer (RFC 6901) to the request body value that caused the error (e.g. /email, /attributes/firstName).

string

parameter

The URI query parameter that caused the error (e.g. pageSize, name[invalid]).

string

Example

{
  "type": "https://docs.postlever.com/error-codes#permission_error",
  "status": 403,
  "title": "Permission denied",
  "detail": "api key required",
  "code": "permission_error",
  "instance": "/v1/contacts"
}

404

No suppression list with this id exists in your account.

application/json

Error envelope returned by every v1 endpoint for failures, following RFC 9457 Problem Details with code and errors extensions.

object

type

required

URI identifying the problem type; dereferences to its documentation.

string format: uri

status

required

HTTP status code applicable to this problem.

integer

title

required

Short, human-readable summary of the problem type.

string

detail

required

Detailed explanation specific to this occurrence.

string

code

required

Error code identifying the specific error condition.

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error api_error contact_exists operation_in_progress

instance

URI reference identifying this specific occurrence (the request URI).

string format: uri-reference

errors

Provides additional information when the error relates to specific request fields.

Array<object>

object

detail

required

Detailed explanation for this specific field error.

string

pointer

JSON Pointer (RFC 6901) to the request body value that caused the error (e.g. /email, /attributes/firstName).

string

parameter

The URI query parameter that caused the error (e.g. pageSize, name[invalid]).

string

Example

{
  "type": "https://docs.postlever.com/error-codes#not_found_error",
  "status": 404,
  "title": "Not found",
  "detail": "Suppression list not found",
  "code": "not_found_error",
  "instance": "/v1/suppression-lists/497f6eca-6276-4993-bfeb-53cbbbba6f08/records"
}

409

An import is already in flight for this suppression list — a file upload, or another add-records request (code: operation_in_progress). A list takes one import at a time so each run’s counts describe only its own records. Retry after the number of seconds given in the Retry-After header.

application/json

Error envelope returned by every v1 endpoint for failures, following RFC 9457 Problem Details with code and errors extensions.

object

type

required

URI identifying the problem type; dereferences to its documentation.

string format: uri

status

required

HTTP status code applicable to this problem.

integer

title

required

Short, human-readable summary of the problem type.

string

detail

required

Detailed explanation specific to this occurrence.

string

code

required

Error code identifying the specific error condition.

string

Allowed values: invalid_request_error authentication_error permission_error not_found_error conflict_error api_error contact_exists operation_in_progress

instance

URI reference identifying this specific occurrence (the request URI).

string format: uri-reference

errors

Provides additional information when the error relates to specific request fields.

Array<object>

object

detail

required

Detailed explanation for this specific field error.

string

pointer

JSON Pointer (RFC 6901) to the request body value that caused the error (e.g. /email, /attributes/firstName).

string

parameter

The URI query parameter that caused the error (e.g. pageSize, name[invalid]).

string

Example

{
  "type": "https://docs.postlever.com/error-codes#operation_in_progress",
  "status": 409,
  "title": "Conflict",
  "detail": "An import is already in progress for this suppression list, retry later",
  "code": "operation_in_progress",
  "instance": "/v1/suppression-lists/497f6eca-6276-4993-bfeb-53cbbbba6f08/records"
}

Headers

Retry-After

integer

Seconds to wait before retrying.

Add records to a suppression list

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

201

Example

400

Examples

401

Example

403

Example

404

Example

409

Example

Headers

Request Body^required