Capability Checks

Capability checks tell you whether a recipient handle can receive iMessage or RCS right now. Use them to pick the right protocol, 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.

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.

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. Caching results as described above is the easiest way to stay under the limit. See Rate Limits for the full response shape and retry handling.

Related

• Protocol Selection — how services are picked and what each supports
• Sending Messages — using preferred_service on send
• Key Concepts: Handles — the handle model
• Rate Limits — handling 429 responses from capability endpoints
• API Reference: Capability — complete endpoint specification