---
title: Capability Checks | API Docs
description: Probe whether a handle can receive iMessage or RCS before sending.
---

Capability checks tell you whether a recipient handle can receive **iMessage** or **RCS** right now. Use them to pick the right [protocol](/guides/messaging/protocol-selection/index.md), to gate rich-only features (effects, decorations), or to fall back gracefully to SMS when a richer service isn’t available.

You do not need to capability-check every send — the API selects the best available service automatically when `preferred_service` is omitted. Capability checks matter when you want to make product decisions *before* calling `POST /v3/chats`.

## Check iMessage capability

POST the recipient handle to `/v3/capability/check_imessage`. The response includes an `available` boolean — branch on it to decide whether to use iMessage-only features. See the [Check iMessage API reference](/api/resources/capability/methods/check_imessage/index.md).

```
const result = await client.capability.checkImessage({ address: '+15556667777' });
if (result.available) {
  // Recipient is reachable on iMessage — safe to use effects, decorations, etc.
}
```

## Check RCS capability

Same shape against `/v3/capability/check_rcs`. See the [Check RCS API reference](/api/resources/capability/methods/check_rcs/index.md).

## Request fields

| Field     | Required | Description                                                                                |
| --------- | -------- | ------------------------------------------------------------------------------------------ |
| `address` | Yes      | Recipient handle — phone number (E.164) or email address for iMessage                      |
| `from`    | No       | One of your provisioned numbers to run the check from — pins the result to a specific line |

## When to use each service

| If the check says… | Do this                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| iMessage capable   | Send with `preferred_service: "iMessage"` to unlock effects, decorations, read receipts, editing |
| RCS capable        | Send with `preferred_service: "RCS"` for rich features on Android                                |
| Neither            | Fall back to SMS/MMS, or let automatic selection pick SMS                                        |

## Caching results

Capability is a property of the recipient’s device and account, not a static attribute of the phone number — a user switching from iPhone to Android, or disabling iMessage, changes the answer. Cache results only briefly (minutes, not days), and refresh on any `message.failed` event whose error suggests a service mismatch.

## Rate limits

Capability check endpoints are rate-limited to prevent abuse (e.g. using them to enumerate which numbers are on iMessage). Excessive calls return HTTP `429` with a `Retry-After` header and [error code `1007`](/error/codes/1xxx/1007/index.md). Caching results as described above is the easiest way to stay under the limit. See [Rate Limits](/guides/platform/rate-limits#capability-check-rate-limit/index.md) for the full response shape and retry handling.

## Related

- [Protocol Selection](/guides/messaging/protocol-selection/index.md) — how services are picked and what each supports
- [Sending Messages](/guides/messaging/sending-messages/index.md) — using `preferred_service` on send
- [Key Concepts: Handles](/getting-started/key-concepts#handles/index.md) — the handle model
- [Rate Limits](/guides/platform/rate-limits#capability-check-rate-limit/index.md) — handling `429` responses from capability endpoints
- [API Reference: Capability](/api/resources/capability/index.md) — complete endpoint specification