API reference · v1
Suppressions
Manage the email do-not-contact list. Requires an admin key.
List suppressions
GET
/v1/contacts/suppressionsLists suppressions for the caller's space, newest first. Includes global suppressions (not space-scoped) alongside space-scoped ones, since both block sends to the caller's contacts. Requires an admin key.
Query parameters
- Name
identifier- Type
- string (email)
- Description
- Filter to the suppression(s) for one email address.
- Name
limit- Type
- integer
- Description
- Page size. Clamped to 1..200 with a warning if out of range.
- Name
offset- Type
- integer
- Description
- Rows to skip. Negative values clamp to 0 with a warning; above 10000 returns 400 offset_too_large. pagination.hasMore becomes false when the next offset reaches the cap even if totalCount is larger. Records list has no ad-hoc filter; this is not an unlimited export contract.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/contacts/suppressions' \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"Response
{
"data": [
{
"id": "csp_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"communicationChannel": "email",
"reason": "manual",
"notes": "string",
"scope": "space",
"identifierHash": "string",
"affectedContactCount": 0
}
],
"pagination": {
"limit": 0,
"offset": 0,
"totalCount": 0,
"hasMore": false
},
"warnings": []
}Status codes
- 200A page of suppressions.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Create a suppression
POST
/v1/contacts/suppressionsSuppresses an email identifier for the space. Requires an admin key. Not Idempotency-Key aware. Error: suppression_already_exists (409; manual and legal are distinct reasons).
Request body
Send JSON with Content-Type: application/json. A body is required.
- Name
identifier- Type
- string (email)
- Requirement
- Required
- Description
- The email address to suppress.
- Name
reason- Type
- string
- Requirement
- Required
- Description
- Allowed values: "manual", "legal".
- Name
notes- Type
- string | null
- Description
- See the request example and OpenAPI schema for this field.
Request
curl --fail-with-body 'https://api.maxclicks.ai/v1/contacts/suppressions' \
-X POST \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"identifier": "[email protected]",
"reason": "manual",
"notes": "string"
}'Response
{
"data": {
"id": "csp_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"communicationChannel": "email",
"reason": "manual",
"notes": "string",
"scope": "space",
"identifierHash": "string",
"affectedContactCount": 0
},
"warnings": []
}Status codes
- 201The created suppression.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 409The write conflicts with an existing resource or the resource's current state.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 429The rate limit was exceeded.
- 500The API failed to process a valid request.
Batch-create suppressions
POST
/v1/contacts/suppressions/batchBulk-creates 1 to 100 suppressions in one call. Each item is validated and processed independently: an existing suppression for the same identifier and reason returns exists rather than failing the item. Requires an admin key. Supports Idempotency-Key. Always responds 200.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request body
Send JSON with Content-Type: application/json. A body is required.
- Name
suppressions- Type
- object[]
- Requirement
- Required
- Description
- See the request example and OpenAPI schema for this field.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/contacts/suppressions/batch' \
-X POST \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}" \
-H "Content-Type: application/json" \
-d '{
"suppressions": [
{
"identifier": "[email protected]",
"reason": "manual",
"notes": "string"
}
]
}'Response
{
"data": {
"results": [
{
"index": 0,
"status": "created",
"error": {
"type": "invalid_request_error",
"code": "string",
"message": "string",
"issues": [
"string"
]
},
"id": "csp_BcwDvBUeSaSDILA5tHgpmU7I",
"createdAt": "2025-01-15T10:30:00.000Z",
"communicationChannel": "email",
"reason": "manual",
"notes": "string",
"scope": "space",
"identifierHash": "string",
"affectedContactCount": 0
}
],
"summary": {
"created": 0,
"exists": 0,
"failed": 0
}
},
"warnings": []
}Status codes
- 200Per-item results and a summary.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 409The write conflicts with an existing resource or the resource's current state.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Batch-delete suppressions
POST
/v1/contacts/suppressions/batch-removeBulk-removes 1 to 100 suppressions by id in one call. Each id is gated exactly like the single delete (must belong to the caller's space; reason must be manual or legal). Requires an admin key. Supports Idempotency-Key. Always responds 200.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request body
Send JSON with Content-Type: application/json. A body is required.
- Name
ids- Type
- string[]
- Requirement
- Required
- Description
- See the request example and OpenAPI schema for this field.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/contacts/suppressions/batch-remove' \
-X POST \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"string"
]
}'Response
{
"data": {
"results": [
{
"index": 0,
"status": "removed",
"error": {
"type": "invalid_request_error",
"code": "string",
"message": "string",
"issues": [
"string"
]
}
}
],
"summary": {
"removed": 0,
"failed": 0
}
},
"warnings": []
}Status codes
- 200Per-item results and a summary.
- 400The request was malformed or failed validation. Also covers
malformed_json(body is not valid JSON) and, on list endpoints,offset_too_large. - 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 409The write conflicts with an existing resource or the resource's current state.
- 413The request body exceeds the 10 MB limit.
- 415The request used an unsupported content type, charset, or content encoding.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Delete a suppression
DELETE
/v1/contacts/suppressions/{id}Deletes a manual or legal suppression. Requires admin permission and supports Idempotency-Key. Missing suppression returns suppression_not_found; automatic provider bounce/complaint suppressions cannot be removed through this endpoint. Removing a suppression is separate from granting contact marketing consent.
Path parameters
- Name
id- Type
- string
- Requirement
- Required
- Description
- The suppression id.
Headers
- Name
Idempotency-Key- Type
- string
- Description
- Stable key for one logical write, maximum 256 characters. Scoped to calling API key, method, and resolved path, with a canonical request-body fingerprint. Replays recorded status/body with Idempotent-Replay=true, including recorded errors. Changed input returns 422 idempotency_key_reused; active work returns 409 idempotency_conflict; unresolved work returns idempotency_outcome_unknown. Completed records expire after 24 hours; unresolved records remain for reconciliation.
Request
# Set MAXCLICKS_OPERATION_KEY once per logical write; reuse it and the body on retries.
curl --fail-with-body 'https://api.maxclicks.ai/v1/contacts/suppressions/csp_BcwDvBUeSaSDILA5tHgpmU7I' \
-X DELETE \
-H "Authorization: Bearer $MAXCLICKS_API_KEY" \
-H "Idempotency-Key: ${MAXCLICKS_OPERATION_KEY:?Set MAXCLICKS_OPERATION_KEY first}"Response
{
"data": {
"id": "csp_BcwDvBUeSaSDILA5tHgpmU7I",
"deleted": true
},
"warnings": []
}Status codes
- 200The suppression was removed.
- 401The API key is missing or invalid.
- 403The key lacks permission, or the space is out of scope.
- 404The referenced resource was not found.
- 409The write conflicts with an existing resource or the resource's current state.
- 422The request was well-formed but could not be processed, typically a failed AI-generation call or a readiness gate (which may carry
error.issues). - 429The rate limit was exceeded.
- 500The API failed to process a valid request.
- 503The operation outcome could not be confirmed. Preserve Operation-Id and the original key/body; reconcile before a new operation.
Working with these endpoints? See error handling, safe retries, client library guides, and the complete OpenAPI schema.