Suppressions

Control which recipients can receive emails from your account.

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": "50025f6a-d4fd-4a23-9e2e-bbee1cf67d2b"
      },
      {
        "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": "50025f6a-d4fd-4a23-9e2e-bbee1cf67d2b"
      }
    ]
  }
}

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/50025f6a-d4fd-4a23-9e2e-bbee1cf67d2b/[email protected]&emailType=0&pageSize=50

Pagination for Large Lists

Retrieve suppressions in manageable chunks:

GET https://api.cm.com/email/suppression/v1/accounts/50025f6a-d4fd-4a23-9e2e-bbee1cf67d2b/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

Add Manual Suppressions​

Request Header​

Request Body​

Response Body​

Error Responses​

Add Suppression via Unique Key​

Request Header​

Request Body​

Response Body​

Error Responses​

List Suppressions​

Request Header​

Response Body​

Error Response​

Suppression Types​

Email Types​

Request Parameters​

Manual Suppression Request Fields​

Unique Key Suppression Request Fields​

Suppression List Response Fields​

Example Use Cases​

Marketing Campaign Opt-out​

Email List Hygiene​

Segment-Specific Suppressions​

Search and Filter Suppressions​

Pagination for Large Lists​

Rate Limits and Constraints​

Troubleshooting​

Add Manual Suppressions

Request Header

Request Body

Response Body

Error Responses

Add Suppression via Unique Key

Request Header

Request Body

Response Body

Error Responses

List Suppressions

Request Header

Response Body

Error Response

Suppression Types

Email Types

Request Parameters

Manual Suppression Request Fields

Unique Key Suppression Request Fields

Suppression List Response Fields

Example Use Cases

Marketing Campaign Opt-out

Email List Hygiene

Segment-Specific Suppressions

Search and Filter Suppressions

Pagination for Large Lists

Rate Limits and Constraints

Troubleshooting