Look up what a number supports
Before you send, you can ask what a number can actually receive. It works on any number — not just the ones on your account, and not just ones you’ve messaged before.
Reading the answer
supports describes the number you asked about, not your own line. Each key is a channel, and the value says whether that number can be reached there.
More channels arrive as more keys. Read the ones you care about by name — supports.imessage — rather than assuming the whole set, so a new key never breaks your code.
It’s a point-in-time answer
This is a live check, not a stored property of the number. Someone who switches device or turns the service off stops being reachable, and the same number can answer differently next week.
true is a strong signal for choosing a channel. It is not a promise that a later send will be delivered — that still depends on the recipient’s device and network at the moment you send.
A failed lookup is never a verdict
If Dial can’t complete a check — on either channel — the whole request fails rather than guessing. You get a 502, or a 429 if you’ve made too many lookups. Nothing partial comes back: there’s no response where one channel answered and the other reports a failure.
So each value keeps exactly one meaning:
Never we couldn’t find out — that’s the 502. The distinction matters if you branch on the result: a 502 is worth retrying, a false isn’t.
Rate limits
Lookups are capped per account, both as a short burst and over a rolling hour. Over either cap the request fails with a 429 carrying a Retry-After header saying how long to wait. See Number lookup limits.
Two things keep you well clear of it in normal use: repeated lookups of the same number are served from a short-lived cache and don’t count, and picking a channel once per conversation is far below the cap. A loop that looks numbers up as fast as it can is what the cap is there to stop.
Picking a channel with it
The common use is deciding how to reach someone before you spend a send:
A number that supports neither can still be reached by SMS — the lookup tells you which rail to pick, not whether the person is reachable at all.