Check iMessage capability

POST/v3/capability/check_imessage

Check whether a recipient address (phone number or email) is reachable via iMessage.

Body ParametersJSONExpand Collapse

address: string

The recipient address to check. check_imessage accepts an E.164 phone number or an email address; check_rcs accepts an E.164 phone number only and rejects an email with a 400, since RCS has no email addressing.

from: optional string

Optional sender phone number. If omitted, an available phone from your pool is used automatically.

ReturnsExpand Collapse

HandleCheckResponse object { address, available, reason, selected_service }

address: string

The recipient address that was checked

available: boolean

Whether the recipient supports the checked messaging service

reason: optional "not_supported"

Why available is false. Only present on a negative result.

not_supported is the only value returned with a 200, and it means the check completed and the recipient is genuinely not reachable over this service. On check_rcs, sender-side faults do not return 200 — they return 503 with a specific error code. check_imessage does not use this mapping.

selected_service: optional string

The service that would actually carry a message to this address right now, which is not always the service you checked — a recipient without RCS resolves to SMS. Absent when the check could not determine one.

Check iMessage capability

curl https://api.linqapp.com/api/partner/v3/capability/check_imessage \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY" \
    -d '{
          "address": "+15551234567",
          "from": "+15559876543"
        }'

{
  "address": "+15551234567",
  "available": true
}

{
  "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": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 429,
    "code": 1007,
    "message": "Rate limited. Try again in 45 seconds.",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1007/",
    "retry_after": 45
  },
  "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

{
  "address": "+15551234567",
  "available": true
}

{
  "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": 403,
    "code": 2005,
    "message": "Access denied - insufficient permissions for this resource",
    "doc_url": "https://docs.linqapp.com/error/codes/2xxx/2005/"
  },
  "success": false
}

{
  "error": {
    "status": 429,
    "code": 1007,
    "message": "Rate limited. Try again in 45 seconds.",
    "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1007/",
    "retry_after": 45
  },
  "success": false
}

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