Suppressions
Manage and add your suppressions using the API
Add Manual Suppressions
Add suppressions manually with detailed sender and recipient information.
Request Header
POST https://api.cm.com/email/suppression/v1/accounts/{logicalAccountId}/manual
Content-Type: application/json
Parameter | Type | Required | Description |
---|---|---|---|
logicalAccountId | UUID | Yes | The logical account identifier |
Header Name | Type | Required | Description |
---|---|---|---|
Content-Type | string | Yes | Must be "application/json" |
Request Body
[
{
"sender": "[email protected]",
"recipient": "[email protected]",
"unsubscribeType": 1,
"emailType": 0
},
{
"sender": "[email protected]",
"recipient": "[email protected]",
"unsubscribeType": 1,
"emailType": 1
}
]
- Maximum 10 suppression requests per API call
- All fields are required for each suppression entry
Response Body
Successful Response (200)
{
"success": true,
"message": "Success",
"status": 200,
"data": null
}
Error Responses
Invalid Request - Empty Account ID (400)
{
"success": true,
"message": "Logical account is empty",
"status": 200,
"data": null
}
Invalid Request - Null Request (400)
{
"success": true,
"message": "Manual unsubscribe request object is null",
"status": 200,
"data": null
}
Request Limit Exceeded (400)
{
"success": false,
"message": "Unsubscription requests are restricted to 10 recipients at a time",
"status": 400,
"data": null
}
Server Error (500)
{
"success": false,
"message": "Failed to unsubscribe from email list",
"status": 500,
"data": null
}
Add Suppression via Unique Key
Handle unsubscribes from email unsubscribe links using unique keys.
Request Header
POST https://api.cm.com/email/suppression/v1/{uniqueKey}
Content-Type: application/json
Parameter | Type | Required | Description |
---|---|---|---|
uniqueKey | UUID | Yes | Unique key from email unsubscribe link |
Request Body
With Reason (Optional)
{
"unsubscribeReason": "No longer interested in marketing emails"
}
Without Reason (Optional)
{
"unsubscribeReason": null
}
Response Body
Successful Response (200)
{
"success": true,
"message": "Success",
"status": 200,
"data": null
}
Error Responses
Invalid Unique Key (400)
{
"success": false,
"message": "Unique key value is empty",
"status": 400,
"data": null
}
Invalid Unsubscribe Link (400)
{
"success": false,
"message": "Cannot unsubscribe from link",
"status": 400,
"data": null
}
List Suppressions
Retrieve suppression data with filtering and pagination options.
Request Header
GET https://api.cm.com/email/suppression/v1/accounts/{logicalAccountId}/subscriptions?searchEmail={email}&emailType={type}&pageSize={size}&pageNumber={page}
Parameter | Type | Required | Description |
---|---|---|---|
logicalAccountId | UUID | Yes | The logical account identifier |
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
searchEmail | string | No | null | Search for specific email address |
emailType | integer | No | -1 | Filter by email type (-1=all, 0=market, 1=high, 2=low) |
pageSize | integer | No | 10 | Number of results per page (1-100) |
pageNumber | integer | No | 1 | Page number to retrieve (1-based) |
Response Body
Successful Response (200)
{
"success": true,
"message": "",
"status": 200,
"data": {
"count": 258,
"unsubscribedEmails": [
{
"id": 1661,
"messageRequestId": "00000000-0000-0000-0000-000000000000",
"sender": "[email protected]",
"recipient": "[email protected]",
"createdAt": "2025-10-16T23:01:24.158221+00:00",
"modifiedAt": null,
"reason": "Manually unsubscribed by user",
"emailType": 0,
"unsubscribeType": 1,
"logicalAccount": "903e1cef-84b3-4500-a9a5-b2ca219f76f5"
},
{
"id": 1660,
"messageRequestId": "00000000-0000-0000-0000-000000000000",
"sender": "[email protected]",
"recipient": "[email protected]",
"createdAt": "2025-10-16T22:57:36.7574+00:00",
"modifiedAt": null,
"reason": "Manually unsubscribed by user",
"emailType": 0,
"unsubscribeType": 1,
"logicalAccount": "903e1cef-84b3-4500-a9a5-b2ca219f76f5"
}
]
}
}
Empty Results Response (200)
{
"success": true,
"message": "",
"status": 200,
"data": {
"count": 0,
"unsubscribedEmails": [
]
}
}
Error Response
Error Response (400)
{
"success": false,
"message": "Failed to fetch email unsubscribe data.",
"status": 400,
"data": null
}
Error Response (500)
{
"success": false,
"message": "Failed to fetch email unsubscribe data.",
"status": 500,
"data": null
}
Suppression Types
The system supports different types of suppressions based on how they were initiated:
Suppression Type | Enum Value | Description | Usage |
---|---|---|---|
HardBounce | 1 | Permanent delivery failure | Invalid email addresses, non-existent domains |
SoftBounce | 2 | Temporary delivery failure | Mailbox full, server temporarily unavailable |
RequestedBySystem | 3 | System-initiated suppression | Automated suppressions based on system rules |
RequestedByAdmin | 4 | Admin-initiated suppression | Manual suppressions by administrators |
UnsubscribedByLink | 5 | Unsubscribed via email unsubscribe link | Unique key unsubscribes with reason |
UnsubscribedByHeader | 6 | Unsubscribed via email header action | Unique key unsubscribes without reason |
ManuallyUnsubscribed | 7 | Manually added by user or admin | Manual suppressions via API |
Email Types
The system categorizes emails into different priority levels:
Email Type | Enum Value | Description | Use Cases |
---|---|---|---|
Market | 0 | Marketing and promotional emails | Newsletters, promotions, campaigns |
HighPriority | 1 | High priority transactional emails | Password resets, security alerts |
LowPriority | 2 | Low priority transactional emails | Notifications, updates |
All Types | -1 | Filter for all email types (GET only) | Used in list filtering |
Request Parameters
Manual Suppression Request Fields
Field | Type | Required | Description |
---|---|---|---|
sender | string | Yes | Email address of the sender (email format) |
recipient | string | Yes | Email address of the recipient (email format) |
unsubscribeType | integer | Yes | Suppression type (1=Manual, 2=Link, 3=Header) |
emailType | integer | Yes | Email type (0=Market, 1=HighPriority, 2=LowPriority) |
Unique Key Suppression Request Fields
Field | Type | Required | Description |
---|---|---|---|
unsubscribeReason | string | No | Optional reason for unsubscribing |
Suppression List Response Fields
Field | Type | Description |
---|---|---|
id | integer | Unique suppression record ID |
messageRequestId | UUID | Original message request identifier |
sender | string | Email address of the sender |
recipient | string | Email address of the recipient |
createdAt | datetime | When the suppression was created |
modifiedAt | datetime | When the suppression was last modified |
reason | string | Reason for the suppression |
emailType | integer | Email type (0=Market, 1=HighPriority, 2=LowPriority) |
unsubscribeType | integer | Suppression type (1=Manual, 2=Link, 3=Header) |
logicalAccount | UUID | Logical account identifier |
Example Use Cases
Marketing Campaign Opt-out
[
{
"sender": "[email protected]",
"recipient": "[email protected]",
"unsubscribeType": 1,
"emailType": 0
}
]
Email List Hygiene
Suppress bounced or invalid email addresses:
[
{
"sender": "[email protected]",
"recipient": "[email protected]",
"unsubscribeType": 1,
"emailType": 0
}
]
Segment-Specific Suppressions
Suppress high-priority emails for specific users:
[
{
"sender": "[email protected]",
"recipient": "[email protected]",
"unsubscribeType": 1,
"emailType": 1
}
]
Search and Filter Suppressions
Find all marketing suppressions for a specific domain:
GET https://api.cm.com/email/suppression/v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/[email protected]&emailType=0&pageSize=50
Pagination for Large Lists
Retrieve suppressions in manageable chunks:
GET https://api.cm.com/email/suppression/v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/subscriptions?pageSize=25&pageNumber=3
Rate Limits and Constraints
- Manual Suppressions: Maximum 10 suppressions per request
- Pagination: Maximum 100 results per page
- Search: Email search supports partial matching
Troubleshooting
- Suppression Not Working: Verify logical account ID and email format
- Search Not Finding Results: Verify search terms and email type filters
- Unique Key Invalid: Ensure unique key is valid and not expired
- Batch Limit Exceeded: Split large suppression lists into batches of 10 or few
Updated about 22 hours ago