BluetickedDeveloper docs
Sign inCreate account

Suppression

3 endpoints, each with examples that open in the console prefilled.

All resourcesGuide: Suppression and opt-outs
GET/api/v1/suppressionsuppression:readTry in console

List suppression entries

List do-not-contact entries (opt-outs), newest first, with cursor pagination.

Query parameters
channelstring
  • Suppressed identifiers are excluded from every send automatically, single sends and campaigns alike.
  • A STOP reply, on WhatsApp as well as SMS, suppresses the sender on every channel and every topic, with reason stop_keyword. A permanent email bounce (or one the provider does not classify) and a spam complaint suppress the address; a transient bounce does not.
  • This list works by identifier and before a contact exists; a contact's own suppressed flag (PATCH /api/v1/contacts/{id}) blocks every send to that contact too. Either one stops a send.
  • Filters: channel=, topic=, business_id= (must belong to the workspace), and identifier=. Phone lookups match any South African format (+27…, 27…, 0…, or 9 digits); a number from another country needs its leading + (anything unreadable returns 400); emails match case-insensitively.
  • added_by is the user id for manual dashboard adds, null for system-captured opt-outs (STOP, unsubscribe, API).
  • Page with ?limit= (default 100, max 500) and ?cursor= (the previous page's next_cursor).
curl -X GET "https://app.blueticked.com/api/v1/suppression?channel=whatsapp" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY"
Response
{
  "data": [
    {
      "id": "b57fc118-fd61-4387-9bd3-3b019b2b0d3e",
      "identifier": "+27800000001",
      "channel": "whatsapp",
      "reason": "stop_keyword",
      "reason_detail": null,
      "added_by": null,
      "created_at": "2026-06-12T08:00:00.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}
POST/api/v1/suppressionsuppression:writeTry in console

Add suppression entry

Add a do-not-contact entry. Idempotent: re-adding returns the existing entry.

Body parameters
identifierrequiredstring
channelrequiredstring
reasonstring
reason_detailstring
  • Use channel "all" to block every channel for the identifier; channel is one of all, whatsapp, sms, email.
  • reason is normalized on write: manual is stored as manual_add and complaint as spam_report, so the response reason can differ from what you sent. Accepted reasons: manual_add, stop_keyword, unsubscribe_link, preference_center, csv_import, bounce, spam_report.
  • topic (all | marketing | transactional) scopes the block and defaults to all; hard reasons (stop_keyword / bounce / spam_report) always force all, and unsubscribe_link / preference_center force marketing.
  • Re-adding an identifier that is already suppressed returns the existing row with already_present: true (a 200, not a 201), so the call stays safe to retry.
curl -X POST "https://app.blueticked.com/api/v1/suppression" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "+27800000001",
  "channel": "all",
  "reason": "manual",
  "reason_detail": "Opted out via CRM"
}'
Response
{
  "entry": {
    "id": "b57fc118-fd61-4387-9bd3-3b019b2b0d3e",
    "business_id": null,
    "identifier": "+27800000001",
    "channel": "all",
    "topic": "all",
    "reason": "manual_add",
    "reason_detail": "Opted out via CRM",
    "added_by": null,
    "created_at": "2026-06-12T08:00:00.000Z"
  },
  "already_present": false,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}
DELETE/api/v1/suppression/{id}suppression:writeTry in console

Remove a suppression entry

Remove a do-not-contact entry so the identifier becomes contactable again.

  • Use this to reverse a manual opt-out.
  • Bounce and spam-complaint entries are hard-refused with a 403 (forbidden): they mark mailboxes that rejected or reported this sender, so removing them would damage deliverability. Clear them from the dashboard only if you are certain.
  • STOP / unsubscribe / preference-center entries require the X-Confirm-Reconsent: true header. Only send it after the recipient explicitly asked to resume. Without it they answer 400 validation_failed; the SDK sends it with { confirmReconsent: true }. An id that is not a UUID answers 400 too.
  • sms_still_globally_blocked: true means the number remains on the platform-wide STOP list from a separate event, so SMS to it still will not send.
curl -X DELETE "https://app.blueticked.com/api/v1/suppression/{id}" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY" \
  -H "X-Confirm-Reconsent: true"
Response
{
  "deleted": true,
  "id": "b57fc118-fd61-4387-9bd3-3b019b2b0d3e",
  "sms_still_globally_blocked": false,
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}