# Blocked Handles

## List blocked handles

`client.BlockedHandles.List(ctx) (*BlockedHandleListResponse, error)`

**get** `/v3/blocked_handles`

Returns all handles you have blocked. Inbound messages from a blocked
handle are dropped and produce no webhooks, and direct sends to a
blocked handle are rejected with `403` (error code `2026`). Group
sends that include unblocked members are not restricted.

### Returns

- `type BlockedHandleListResponse struct{…}`

  - `BlockedHandles []BlockedHandleEntry`

    All handles blocked by the partner, newest first

    - `BlockedAt Time`

      When the handle was blocked

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

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/linq-team/linq-go"
  "github.com/linq-team/linq-go/option"
)

func main() {
  client := linqgo.NewClient(
    option.WithAPIKey("My API Key"),
  )
  blockedHandles, err := client.BlockedHandles.List(context.TODO())
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", blockedHandles.BlockedHandles)
}
```

#### Response

```json
{
  "blocked_handles": [
    {
      "handle": "+12025551234",
      "reason": "spam",
      "blocked_at": "2026-07-30T16:42:00Z"
    }
  ]
}
```

## Block a handle

`client.BlockedHandles.Block(ctx, body) (*BlockedHandleBlockResponse, error)`

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

### Parameters

- `body BlockedHandleBlockParams`

  - `Handle param.Field[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 param.Field[string]`

    Optional free-text note on why the handle was blocked

### Returns

- `type BlockedHandleBlockResponse struct{…}`

  - `BlockedHandle BlockedHandleEntry`

    - `BlockedAt Time`

      When the handle was blocked

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

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/linq-team/linq-go"
  "github.com/linq-team/linq-go/option"
)

func main() {
  client := linqgo.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.BlockedHandles.Block(context.TODO(), linqgo.BlockedHandleBlockParams{
    Handle: "+12025551234",
    Reason: linqgo.String("spam"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.BlockedHandle)
}
```

#### Response

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

## Unblock a handle

`client.BlockedHandles.Unblock(ctx, body) error`

**delete** `/v3/blocked_handles`

Removes a handle from your blocklist. Inbound messages from it will be
delivered again and sends to it are allowed again. The handle goes in
the request body, mirroring block — no URL encoding needed.

### Parameters

- `body BlockedHandleUnblockParams`

  - `Handle param.Field[string]`

    The handle to unblock

### Example

```go
package main

import (
  "context"

  "github.com/linq-team/linq-go"
  "github.com/linq-team/linq-go/option"
)

func main() {
  client := linqgo.NewClient(
    option.WithAPIKey("My API Key"),
  )
  err := client.BlockedHandles.Unblock(context.TODO(), linqgo.BlockedHandleUnblockParams{
    Handle: "+12025551234",
  })
  if err != nil {
    panic(err.Error())
  }
}
```

#### Response

```json
{
  "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
}
```

## Domain Types

### Blocked Handle Entry

- `type BlockedHandleEntry struct{…}`

  - `BlockedAt Time`

    When the handle was blocked

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