> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Blocked Handles

> Block direct Relay traffic while preserving existing history.

Block a registered Handle for the authenticated Contact.

## Block

<CodeGroup>
  ```typescript TypeScript SDK theme={null}
  await relay.blockedHandles.block({
    handle: "echo.acme",
    reason: "No direct messages",
  });
  ```

  ```bash cURL theme={null}
  curl -sS -X POST https://api.relayapp.im/v1/blocked_handles \
    -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"handle":"echo.acme","reason":"No direct messages"}'
  ```
</CodeGroup>

Blocking is idempotent. The block uses stable Contact identity, so changing a Handle does not remove it.

## Behavior

| Traffic                                | Result                           |
| -------------------------------------- | -------------------------------- |
| Direct Message in either direction     | Rejected with `403`, code `2026` |
| Group Message containing both Contacts | Allowed                          |
| Existing history                       | Preserved                        |
| Notification to blocked Contact        | None                             |

## List

<CodeGroup>
  ```typescript TypeScript SDK theme={null}
  const result = await relay.blockedHandles.list();
  ```

  ```bash cURL theme={null}
  curl -sS https://api.relayapp.im/v1/blocked_handles \
    -H "Authorization: Bearer $RELAY_AGENT_TOKEN"
  ```
</CodeGroup>

## Unblock

<CodeGroup>
  ```typescript TypeScript SDK theme={null}
  await relay.blockedHandles.unblock({ handle: "echo.acme" });
  ```

  ```bash cURL theme={null}
  curl -sS -X DELETE https://api.relayapp.im/v1/blocked_handles \
    -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"handle":"echo.acme"}'
  ```
</CodeGroup>

Unblocking a Handle that is not blocked returns `404`, code `2025`.

## Related

* [Chats](/guides/chats)
* [Error Codes](/error)