Email Suppressions

Our Email Suppressions API enables developers to manage email unsubscribes and suppressions for their email campaigns. The API provides comprehensive suppression management capabilities including manual suppressions, link-based unsubscribes, and suppression retrieval with filtering and pagination.

Fact Sheet

Feature	Support	Remark
Manual Suppressions	Yes	Add suppressions manually with detailed sender/recipient information
Bulk Suppression Management	Yes	Support for up to 10 suppressions per request
Link-based Unsubscribes	Yes	Handle unsubscribes from email unsubscribe links via unique keys
Pagination & Filtering	Yes	Search by email, filter by email type, paginated results
Multiple Email Types	Yes	Support for Market, High Priority, and Low Priority email types
Suppression Types	Yes	Manual, Link-based, and Header-based suppression tracking
Webhook Integration	Yes	Real-time webhook notifications for suppression events
Account-based Organization	Yes	Suppressions are organized by logical account IDs
Reason Tracking	Yes	Track suppression reasons for compliance and analytics

Managing Email Suppressions

The Email Suppressions API allows you to manage email unsubscribes and suppressions across different channels - manual suppressions and link-based unsubscribes from emails. Each suppression is tracked with detailed metadata including sender, recipient, reason, and suppression type.

Suppression Configuration

Add Manual Suppressions

Add suppressions manually with detailed sender and recipient information.

POST /v1/accounts/{logicalAccountId}/manual
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
logicalAccountId	UUID	Yes	The logical account identifier

Request Headers

Header Name	Type	Required	Description
Content-Type	string	Yes	Must be "application/json"

Request Body Example

[
  {
    "sender": "[email protected]",
    "recipient": "[email protected]",
    "unsubscribeType": 1,
    "emailType": 0
  },
  {
    "sender": "[email protected]", 
    "recipient": "[email protected]",
    "unsubscribeType": 1,
    "emailType": 1
  }
]

Request Body Limits

Maximum 10 suppression requests per API call
All fields are required for each suppression entry

Successful Response (200)

{
  "isSuccess": true,
  "message": "Suppressions added successfully",
  "statusCode": 0,
  "data": null
}

Error Responses

Invalid Request - Empty Account ID (400)

{
  "isSuccess": false,
  "message": "Logical account is empty",
  "statusCode": 400,
  "data": null
}

Invalid Request - Null Request (400)

{
  "isSuccess": false,
  "message": "Manual unsubscribe request object is null",
  "statusCode": 400,
  "data": null
}

Request Limit Exceeded (400)

{
  "isSuccess": false,
  "message": "Unsubscription requests are restricted to 10 recipients at a time",
  "statusCode": 400,
  "data": null
}

Server Error (500)

{
  "isSuccess": false,
  "message": "Failed to unsubscribe from email list",
  "statusCode": 400,
  "data": null
}

Add Suppression via Unique Key

Handle unsubscribes from email unsubscribe links using unique keys.

POST /v1/{uniqueKey}
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
uniqueKey	UUID	Yes	Unique key from email unsubscribe link

Request Body Example

{
  "unsubscribeReason": "No longer interested in marketing emails"
}

Request Body (Optional Reason)

{
  "unsubscribeReason": null
}

Successful Response (200)

{
  "isSuccess": true,
  "message": "Success",
  "statusCode": 0,
  "data": null
}

Error Responses

Invalid Unique Key (400)

{
  "isSuccess": false,
  "message": "Unique key value is empty",
  "statusCode": 400,
  "data": null
}

Invalid Unsubscribe Link (400)

{
  "isSuccess": false,
  "message": "Cannot unsubscribe from link",
  "statusCode": 400,
  "data": null
}

List Suppressions

Retrieve suppression data with filtering and pagination options.

GET /v1/accounts/{logicalAccountId}/subscriptions?searchEmail={email}&emailType={type}&pageSize={size}&pageNumber={page}

Path Parameters

Parameter	Type	Required	Description
logicalAccountId	UUID	Yes	The logical account identifier

Query Parameters

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)

Successful Response (200)

{
  "isSuccess": true,
  "message": "",
  "statusCode": 0,
  "data": {
    "count": 25,
    "unsubscribedEmails": [
      {
        "id": 12345,
        "messageRequestId": "550e8400-e29b-41d4-a716-446655440000",
        "sender": "[email protected]",
        "recipient": "[email protected]",
        "createdAt": "2024-03-15T10:30:00Z",
        "modifiedAt": "2024-03-15T10:30:00Z",
        "reason": "No longer interested in marketing emails",
        "emailType": 0,
        "unsubscribeType": 2,
        "logicalAccount": "903e1cef-84b3-4500-a9a5-b2ca219f76f5"
      },
      {
        "id": 12346,
        "messageRequestId": "660f9511-f3ac-42e5-b827-557766551001", 
        "sender": "[email protected]",
        "recipient": "[email protected]",
        "createdAt": "2024-03-14T15:20:00Z",
        "modifiedAt": "2024-03-14T15:20:00Z",
        "reason": "Manually unsubscribed by user",
        "emailType": 1,
        "unsubscribeType": 1,
        "logicalAccount": "903e1cef-84b3-4500-a9a5-b2ca219f76f5"
      }
    ]
  }
}

Empty Results Response (200)

{
  "isSuccess": true,
  "message": "",
  "statusCode": 0,
  "data": {
    "count": 0,
    "unsubscribedEmails": []
  }
}

Error Response (400)

{
  "isSuccess": false,
  "message": "Invalid data provided",
  "statusCode": 400,
  "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

Status Codes

Status Code	Description
200	OK: Request processed successfully
400	Bad Request: Invalid request data or parameters
500	Internal Server Error: Server-side error

Error Handling

All error responses follow a consistent format:

{
  "isSuccess": false,
  "message": "Human-readable error description",
  "statusCode": 400,
  "data": null
}

Best Practices

Batch Processing: Use the manual suppression endpoint for bulk operations (up to 10 per request)
Reason Tracking: Always provide meaningful reasons for suppressions to aid compliance
Email Type Segmentation: Use appropriate email types to allow granular suppression control
Pagination: Use appropriate page sizes (10-50) for large suppression lists
Validation: Validate email formats before sending suppression requests

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 /v1/accounts/903e1cef-84b3-4500-a9a5-b2ca219f76f5/[email protected]&emailType=0&pageSize=50

Pagination for Large Lists

Retrieve suppressions in manageable chunks:

GET /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