Suppression API Reference

Endpoint

POST https://api.emailelement.com/api/SuppressionList/{listId}/Records

Authentication

x-api-key: YOUR_API_KEY

The API key must have Suppression API permission enabled (Full Access for adding records).

URL Parameters

Parameter	Type	Required	Description
`listId`	integer	Yes	The Suppression List ID

Request Body

{
  "items": [
    "user1@example.com",
    "user2@example.com"
  ]
}

Field	Type	Required	Description
`items`	array of strings	Yes	List of suppression entries to add. Format must match the suppression list type.

By List Type

Email type list:

{
  "items": [
    "bounce1@example.com",
    "bounce2@example.com",
    "complaint@example.com"
  ]
}

MD5 type list:

{
  "items": [
    "5d41402abc4b2a76b9719d911017c592",
    "e99a18c428cb38d5f260853678922e03"
  ]
}

SHA512 type list:

{
  "items": [
    "3c9909afec25354d551dae21590bb26e38d53f2173b8d3dc3eee4c047e7ab1c1eb8b85103e3be7ba613b31bb5c9c36214dc9f14a42fd7a2fdb84856bca5c44c2"
  ]
}

Domain type list:

{
  "items": [
    "baddomain.com",
    "spamdomain.net"
  ]
}

Pattern type list:

{
  "items": [
    "*@baddomain.com",
    "noreply@*",
    "*bot*"
  ]
}

Responses

Success (200 OK)

{
  "succeeded": true,
  "data": [
    "bounce1@example.com",
    "bounce2@example.com"
  ],
  "messages": []
}

Field	Description
`succeeded`	`true` if all records were added successfully
`data`	Array of records that were accepted
`messages`	Empty array when no errors

Unauthorized (401)

{
  "Data": null,
  "Succeeded": false,
  "Message": "Invalid ApiKey"
}

Cause	Fix
Missing `x-api-key` header	Add the header with your API key
Invalid or expired API key	Generate a new API key in EmailElement
API key lacks Suppression API permission	Edit the API key and enable Suppression API Full Access

Suppression List Types

Records submitted must match the list's type. Submitting an email address to an MD5-type list will result in an error.

Type	Format	Example
Email	Full email address	`user@example.com`
MD5	MD5 hash of email (32 hex chars)	`5d41402abc4b2a76b9719d911017c592`
SHA512	SHA-512 hash of email (128 hex chars)	`3c9909afec25354d...`
Domain	Domain name (no @)	`example.com`
Pattern	Wildcard pattern	`@example.com`, `noreply@`, `bot`

Download Records

Step 1: Request a download

POST https://api.emailelement.com/api/SuppressionList/{listId}/Downloads

Response (200 OK):

{
  "downloadLink": "https://api.emailelement.com/api/SuppressionList/2666/Downloads/1017"
}

Step 2: Download the file

GET {downloadLink}

Use the downloadLink URL from the response to download a ZIP file containing a CSV with all suppression records.

Delete Records

DELETE https://api.emailelement.com/api/SuppressionList/{listId}/Records?items={url-encoded-items}

Pass records as a comma-separated, URL-encoded list in the items query parameter.

Example

DELETE https://api.emailelement.com/api/SuppressionList/2672/Records?items=user1%40example.com,user2%40example.com

Note: Special characters in email addresses must be URL-encoded (e.g., + becomes %2B, @ becomes %40).

Error Codes

Status	Meaning	Resolution
200	Success	Records added
400	Bad Request	Record format does not match list type
401	Unauthorized	Check API key and `x-api-key` header
403	Forbidden	API key lacks required permission level
404	Not Found	Suppression List ID is invalid
429	Rate Limited	Reduce request frequency