Blocked Handles

Block phone numbers, emails, short codes, and sender IDs from reaching your Linq lines.

Block handles — phone numbers, email addresses, SMS short codes, or sender IDs. Inbound messages from a blocked handle are dropped before they reach your webhooks, and direct sends to a blocked handle are rejected with 403 (error code 2026). Group sends that include unblocked members are not restricted.

Blocking is the way to shut out bots, spam, and abusive senders without touching your webhook or application code: the block is enforced on both directions of traffic, before anything reaches you.

The blocklist is account-wide — a blocked handle is blocked on every line on your account, not just the line it messaged.

What blocking does

Direction	Behavior
Inbound from a blocked handle	Dropped. No `message.received` webhook, no chat activity, no reply.
Direct send to a blocked handle	Rejected with `403` error `2026`.
Group send that includes a blocked handle	Allowed, as long as at least one recipient is not blocked.

Blocking does not delete existing chats or history with the handle — it only stops new traffic.

Block a handle

A handle is an E.164 phone number, an email address (iMessage sender), an SMS short code (3–8 digits), or an alphanumeric sender ID. See the Block Handle API reference for the full endpoint specification.

cURL

curl -X POST https://api.linqapp.com/api/partner/v3/blocked_handles \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "handle": "+12025551234",
      "reason": "spam"
    }'

Field	Required	Type	Description
`handle`	Yes	`string`	The handle to block: an E.164 phone number, an email address, an SMS short code (3-8 digits), or an alphanumeric sender ID.
`reason`	No	`string`	Optional free-text note on why the handle was blocked

Handles are normalized on the way in — phone numbers to E.164, emails lowercased — so the stored value may differ from what you sent. Blocking is idempotent: re-blocking an already blocked handle returns the existing entry rather than an error.

List blocked handles

Returns every handle on your blocklist, newest first, each with its reason and blocked_at. See the List Blocked Handles API reference.

cURL

curl https://api.linqapp.com/api/partner/v3/blocked_handles \
  -H "Authorization: Bearer $LINQ_API_KEY"

Unblock a handle

The handle goes in the request body — mirroring block, so there’s no URL encoding to get wrong. See the Unblock Handle API reference.

cURL

curl -X DELETE https://api.linqapp.com/api/partner/v3/blocked_handles \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "handle": "+12025551234"
    }'

Unblocking a handle that isn’t on your blocklist returns 404 error 2025. Because handles are stored normalized, unblock with the value returned by GET /v3/blocked_handles rather than the raw string a user typed.