Block a handle

client.blockedHandles.block(, ?): BlockedHandleBlockResponse { blocked_handle }

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

body: BlockedHandleBlockParams { handle, reason }

handle: 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?: string

Optional free-text note on why the handle was blocked

ReturnsExpand Collapse

BlockedHandleBlockResponse { blocked_handle }

blocked_handle: BlockedHandleEntry { blocked_at, handle, reason }

blocked_at: string

When the handle was blocked

formatdate-time

handle: string

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

reason?: string

Optional note recorded when the handle was blocked

Block a handle

import LinqAPIV3 from '@linqapp/sdk';

const client = new LinqAPIV3({
  apiKey: process.env['LINQ_API_V3_API_KEY'], // This is the default and can be omitted
});

const response = await client.blockedHandles.block({ handle: '+12025551234', reason: 'spam' });

console.log(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
}