Block a handle

blocked_handles.block() -> BlockedHandleBlockResponse

POST/v3/blocked_handles

Blocks a handle — an E.164 phone number, an email address (iMessage sender), an SMS short code (e.g. 262966), or an alphanumeric sender ID. Inbound messages from it are dropped and produce no webhooks, and direct sends to it are rejected with 403 (error code 2026); group sends that include unblocked members are not restricted. Blocking is idempotent — re-blocking an already blocked handle returns the existing entry.

ParametersExpand Collapse

handle: str

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: Optional[str]

Optional free-text note on why the handle was blocked

ReturnsExpand Collapse

class BlockedHandleBlockResponse: …

blocked_handle: BlockedHandleEntry

blocked_at: datetime

When the handle was blocked

formatdate-time

handle: str

The blocked handle, normalized (E.164 phone, lowercased email, short code, or sender ID)

reason: Optional[str]

Optional note recorded when the handle was blocked

Block a handle

import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
response = client.blocked_handles.block(
    handle="+12025551234",
    reason="spam",
)
print(response.blocked_handle)

{
  "blocked_handle": {
    "handle": "+12025551234",
    "reason": "spam",
    "blocked_at": "2026-07-30T16:42:00Z"
  }
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}

Returns Examples

{
  "blocked_handle": {
    "handle": "+12025551234",
    "reason": "spam",
    "blocked_at": "2026-07-30T16:42:00Z"
  }
}

{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1002/"
  },
  "success": false
}

{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2004/"
  },
  "success": false
}

{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error",
    "doc_url": "https://docs.linqapp.com/error/codes/3xxx/3006/"
  },
  "success": false
}