Suppress a number or address
const url = 'https://api.connect.ms/v2/suppressions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"number":"example","email":"hello@example.com","scope":"all","reason":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.connect.ms/v2/suppressions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "number": "example", "email": "hello@example.com", "scope": "all", "reason": "example" }'Adds a phone number or email address to the suppression list so it is no longer sent to. For email, scope says which kinds of email are blocked.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”The API version to use, for example 2026-10-01. Defaults to the version set on your API key.
A unique value of up to 255 characters, so a retried request is not acted on twice. Required for keys in Strict API Mode.
Request Bodyrequired
Section titled “Request Bodyrequired”What to suppress. Provide exactly one of number and email.
What to suppress. Provide exactly one of number and email.
object
The phone number to suppress, in any common format; a number without a country code is treated as UK. Stored in E.164 format.
The email address to suppress, up to 320 characters.
What an email suppression blocks: all (every kind of email) or marketing (marketing email only).
A reason for your own reference, up to 256 characters.
Responses
Section titled “Responses”The number, or the address with this scope, was already suppressed; the existing entry is returned.
A phone number or email address that will not be sent to; for email, scope says which kinds are blocked. Either number or email is set.
object
The unique id of the suppression.
The suppressed phone number (E.164 format). Null for an email suppression.
The suppressed email address. Null for a phone suppression.
What an email suppression blocks: all (every kind of email) or marketing (marketing email only).
How the entry got on the suppression list: api (added through the API or dashboard), web (the recipient used an opt-out link), stop (the recipient texted STOP), bounce (a hard bounce, email only), complaint (a spam complaint, email only) or system (added by Connect, email only).
The reason recorded when it was added, or null.
When (UTC) the entry was added.
Example
{ "scope": "all", "source": "api"}The suppression was added.
A phone number or email address that will not be sent to; for email, scope says which kinds are blocked. Either number or email is set.
object
The unique id of the suppression.
The suppressed phone number (E.164 format). Null for an email suppression.
The suppressed email address. Null for a phone suppression.
What an email suppression blocks: all (every kind of email) or marketing (marketing email only).
How the entry got on the suppression list: api (added through the API or dashboard), web (the recipient used an opt-out link), stop (the recipient texted STOP), bounce (a hard bounce, email only), complaint (a spam complaint, email only) or system (added by Connect, email only).
The reason recorded when it was added, or null.
When (UTC) the entry was added.
Example
{ "scope": "all", "source": "api"}The request is not valid. The detail field says why, and errors lists any problems by field name.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The API key or bearer token is missing or not valid, or the request signature could not be verified.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The caller is not allowed to do this.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}A request with this Idempotency-Key is still being processed. Retry after the Retry-After header.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}This Idempotency-Key was already used for a different request. Use a new key.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}This API key requires an Idempotency-Key header on every POST and PATCH.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}The service is temporarily unavailable. Retry after the Retry-After header.
Why a request failed, in the RFC 9457 problem details format.
object
A URI identifying the kind of problem, ending in a code such as validation_failed, not_found, sending_blocked or rate_limited.
A short, fixed summary of the kind of problem.
The HTTP status code of the response.
What went wrong with this particular request, when there is more to say than the title.
For validation failures, the problems found, keyed by field name (nested fields as template.name, list items as messages[3]).
object
The id recorded for this error, matching the Request-Id header when one is sent. Quote it when contacting support.
Example generated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "requestId": "example"}