Suppression List API Documentation

Suppression list management endpoints for browsing, importing, deleting, and aggregating email addresses from the suppression list.

The SuppressionSource column is a fixed enumeration. The valid values are:

• Administrator
• User
• SPAM complaint
• Hard Bounced
• Unsubscribe

Browse Suppression List

POST /api.php

API Usage Notes

• Authentication required: User API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: suppression.browse
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
SearchPattern	String	No	Search pattern for filtering email addresses (supports * wildcard). When supplied, TotalRecords reflects the filtered count.
SuppressionSource	String	No	Restrict results to one or more sources. Comma-separated list of SuppressionSource ENUM values (e.g. Hard Bounced,SPAM complaint).
ListID	Integer	No	Scope the browse to a single subscriber list. When omitted or 0, returns the user-wide global suppression list (today's default behavior). When non-zero, the list must be owned by the authenticated user; otherwise the call fails with ErrorCode: 4.
StartFrom	Integer	No	Starting record index for pagination (default: 0)
RetrieveCount	Integer	No	Number of records to retrieve (default: 100)

Response Shape:

SuppressedEmails is an associative map keyed by email address (not a JSON array). Use Object.values() (or the equivalent in your language) if you need a list. TotalRecords reflects whatever filters (SearchPattern, SuppressionSource) the request set, so paging math always lines up with the rendered page.

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "suppression.browse",
    "SessionID": "your-session-id",
    "SearchPattern": "*@example.com",
    "SuppressionSource": "Hard Bounced,SPAM complaint",
    "StartFrom": 0,
    "RetrieveCount": 50
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "TotalRecords": 12,
  "SuppressedEmails": {
    "user@example.com": {
      "SuppressionID": "1234",
      "RelListID": "0",
      "RelOwnerUserID": "42",
      "EmailAddress": "user@example.com",
      "SuppressionSource": "Hard Bounced",
      "Reason": "Bounce: 550 mailbox unavailable"
    }
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Invalid SuppressionSource value
4: Invalid ListID — list does not exist or is not owned by the authenticated user

Suppression Stats

POST /api.php

Returns the total suppression count and a per-source breakdown for the authenticated user. Useful for rendering "Total / Manual / Bounce / Complaint / Unsubscribe" stat strips without fanning out into multiple suppression.browse calls. All ENUM values are always present in BySource (zero when absent) so typed clients see a stable shape.

API Usage Notes

• Authentication required: User API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: suppression.stats
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
SearchPattern	String	No	Optional pattern for filtering by email (supports * wildcard).
SuppressionSource	String	No	Optional comma-separated list of SuppressionSource ENUM values. When supplied, Total and BySource only reflect those sources.
ListID	Integer	No	Scope the counts to a single subscriber list. When omitted or 0, counts the user-wide global suppression list (today's default behavior). When non-zero, the list must be owned by the authenticated user; otherwise the call fails with ErrorCode: 4.

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "suppression.stats",
    "APIKey": "your-api-key"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "Total": 1240,
  "BySource": {
    "Administrator": 5,
    "User": 312,
    "SPAM complaint": 14,
    "Hard Bounced": 871,
    "Unsubscribe": 38
  }
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Invalid SuppressionSource value
4: Invalid ListID — list does not exist or is not owned by the authenticated user

Delete from Suppression List

POST /api.php

Accepts either a single address (legacy) or a bulk payload. The bulk path returns counts and a list of skipped (invalid) addresses.

API Usage Notes

• Authentication required: User API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: suppression.delete
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
EmailAddress	String	No*	Single email address to remove (legacy single-delete path).
EmailAddresses	String	No*	JSON-encoded array of email addresses (bulk path).
EmailAddressesBulk	String	No*	Newline-separated email addresses (bulk path).
ListID	Integer	No	Scope the delete to a single subscriber list. When omitted or 0, only rows on the user-wide global suppression list are removed (today's default behavior). When non-zero, only rows with matching RelListID are removed; the same address suppressed on other scopes is left untouched. The list must be owned by the authenticated user; otherwise the call fails with ErrorCode: 4.

* At least one of EmailAddress, EmailAddresses, or EmailAddressesBulk is required. When any of the bulk parameters is set, the legacy single-address validation is skipped and the response uses the bulk shape (with TotalDeleted, TotalFailed, FailedEmailAddresses).

Example Request — single

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "suppression.delete",
    "SessionID": "your-session-id",
    "EmailAddress": "user@example.com"
  }'

Example Request — bulk

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "suppression.delete",
    "APIKey": "your-api-key",
    "EmailAddresses": "[\"a@example.com\",\"b@example.com\"]",
    "EmailAddressesBulk": "c@example.com\nd@example.com"
  }'

Success Response — single

{
  "Success": true,
  "ErrorCode": 0
}

Success Response — bulk

{
  "Success": true,
  "ErrorCode": 0,
  "TotalDeleted": 4,
  "TotalFailed": 0,
  "FailedEmailAddresses": []
}

Error Response

{
  "Success": false,
  "ErrorCode": [1]
}

Error Codes

0: Success
1: Missing input — none of EmailAddress, EmailAddresses, or EmailAddressesBulk was provided
2: Invalid email address (single path), email not in suppression list (single path), or invalid JSON in EmailAddresses
4: Invalid ListID — list does not exist or is not owned by the authenticated user

Import to Suppression List

POST /api.php

API Usage Notes

• Authentication required: User API Key or Admin API Key
• Legacy endpoint access via /api.php only (no v1 REST alias configured)

Request Body Parameters:

Parameter	Type	Required	Description
Command	String	Yes	API command: suppression.import
SessionID	String	No	Session ID obtained from login
APIKey	String	No	API key for authentication
EmailAddresses	String	No*	JSON-encoded array of email addresses to import
EmailAddressesBulk	String	No*	Newline-separated list of email addresses to import
SuppressionSource	String	No	Override the source recorded for imported rows. Must be one of the SuppressionSource ENUM values. Defaults to User.
Reason	String	No	Override the reason recorded for imported rows. Capped at 250 characters. Defaults to Suppression List Import.
ListID	Integer	No	Write imported rows scoped to a single subscriber list. When omitted or 0, imports go to the user-wide global suppression list (RelListID = 0, today's default behavior). When non-zero, the list must be owned by the authenticated user; otherwise the call fails with ErrorCode: 4 and no rows are written. Applies to both EmailAddresses and EmailAddressesBulk paths.

* Note: Either EmailAddresses or EmailAddressesBulk must be provided. Both can be provided simultaneously.

Example Request

curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{
    "Command": "suppression.import",
    "SessionID": "your-session-id",
    "EmailAddresses": "[\"user1@example.com\", \"user2@example.com\"]",
    "EmailAddressesBulk": "user3@example.com\nuser4@example.com\nuser5@example.com",
    "SuppressionSource": "Hard Bounced",
    "Reason": "Imported from bounce log 2026-04-30"
  }'

Success Response

{
  "Success": true,
  "ErrorCode": 0,
  "TotalImported": 5,
  "TotalFailed": 0,
  "FailedEmailAddresses": []
}

Error Response

{
  "Success": false,
  "ErrorCode": [1, 2]
}

Error Codes

0: Success
1: Missing EmailAddresses parameter
2: Missing EmailAddressesBulk parameter or invalid EmailAddresses format (both parameters are missing or EmailAddresses JSON is invalid)
3: Invalid SuppressionSource value
4: Invalid ListID — list does not exist or is not owned by the authenticated user