---
title: Blocked Handles | API Docs
description: 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`](/error/codes/2xxx/2026/index.md). |
| 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](/api/resources/blocked_handles/methods/block/index.md) for the full endpoint specification.

- [cURL](#tab-panel-23)

Terminal window

```
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.

Reason is for you, not the sender

`reason` is a free-text note stored with the entry and returned on the list endpoint. Nothing is sent to the blocked handle — blocking is silent from their side.

## 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](/api/resources/blocked_handles/methods/list/index.md).

- [cURL](#tab-panel-22)

Terminal window

```
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](/api/resources/blocked_handles/methods/unblock/index.md).

- [cURL](#tab-panel-24)

Terminal window

```
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`](/error/codes/2xxx/2025/index.md). Because handles are stored normalized, unblock with the value returned by `GET /v3/blocked_handles` rather than the raw string a user typed.

## Related

- [Error 2026 — recipient is blocked](/error/codes/2xxx/2026/index.md)
- [Error 2025 — blocked handle not found](/error/codes/2xxx/2025/index.md)
- [API Reference: Blocked Handles](/api/resources/blocked_handles/index.md)