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
ParameterTypeRequiredDescription
logicalAccountIdUUIDYesThe logical account identifier
Header NameTypeRequiredDescription
Content-TypestringYesMust 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
ParameterTypeRequiredDescription
uniqueKeyUUIDYesUnique 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}
ParameterTypeRequiredDescription
logicalAccountIdUUIDYesThe logical account identifier
ParameterTypeRequiredDefaultDescription
searchEmailstringNonullSearch for specific email address
emailTypeintegerNo-1Filter by email type (-1=all, 0=market, 1=high, 2=low)
pageSizeintegerNo10Number of results per page (1-100)
pageNumberintegerNo1Page 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 TypeEnum ValueDescriptionUsage
HardBounce1Permanent delivery failureInvalid email addresses, non-existent domains
SoftBounce2Temporary delivery failureMailbox full, server temporarily unavailable
RequestedBySystem3System-initiated suppressionAutomated suppressions based on system rules
RequestedByAdmin4Admin-initiated suppressionManual suppressions by administrators
UnsubscribedByLink5Unsubscribed via email unsubscribe linkUnique key unsubscribes with reason
UnsubscribedByHeader6Unsubscribed via email header actionUnique key unsubscribes without reason
ManuallyUnsubscribed7Manually added by user or adminManual suppressions via API

Email Types

The system categorizes emails into different priority levels:

Email TypeEnum ValueDescriptionUse Cases
Market0Marketing and promotional emailsNewsletters, promotions, campaigns
HighPriority1High priority transactional emailsPassword resets, security alerts
LowPriority2Low priority transactional emailsNotifications, updates
All Types-1Filter for all email types (GET only)Used in list filtering

Request Parameters

Manual Suppression Request Fields

FieldTypeRequiredDescription
senderstringYesEmail address of the sender (email format)
recipientstringYesEmail address of the recipient (email format)
unsubscribeTypeintegerYesSuppression type (1=Manual, 2=Link, 3=Header)
emailTypeintegerYesEmail type (0=Market, 1=HighPriority, 2=LowPriority)

Unique Key Suppression Request Fields

FieldTypeRequiredDescription
unsubscribeReasonstringNoOptional reason for unsubscribing

Suppression List Response Fields

FieldTypeDescription
idintegerUnique suppression record ID
messageRequestIdUUIDOriginal message request identifier
senderstringEmail address of the sender
recipientstringEmail address of the recipient
createdAtdatetimeWhen the suppression was created
modifiedAtdatetimeWhen the suppression was last modified
reasonstringReason for the suppression
emailTypeintegerEmail type (0=Market, 1=HighPriority, 2=LowPriority)
unsubscribeTypeintegerSuppression type (1=Manual, 2=Link, 3=Header)
logicalAccountUUIDLogical 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

  1. Suppression Not Working: Verify logical account ID and email format
  2. Search Not Finding Results: Verify search terms and email type filters
  3. Unique Key Invalid: Ensure unique key is valid and not expired
  4. Batch Limit Exceeded: Split large suppression lists into batches of 10 or few