POST /v1/handle-check
Ask Apple whether an address can receive iMessages, before you try to send.
POST /v1/handle-checkAsks Apple's directory whether an address is reachable on iMessage. Use it to avoid sending into a void — a number that is Android-only, or an Apple ID that does not exist.
Unlike commands, this is a synchronous read. The answer is in the HTTP response; nothing arrives on the stream.
Request
Prop
Type
curl $MAPIER_BASE_URL/v1/handle-check \
-H "Authorization: Bearer $MAPIER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "address": "+14155550100" }'Response
{ "address": "+14155550100", "available": true, "idStatus": 1 }{ "address": "+14155550100", "available": false, "idStatus": 0 }Prop
Type
When the check cannot run
A 503 with a reason explains why. No reason is an answer about
reachability — the question either never reached Apple or came back unusable.
All but one describe the service; the exception, invalid_target, is about your
address's grammar rather than whether it is on iMessage, and is documented below
because you should never see it.
{ "error": "handle_check_unavailable", "reason": "read_in_flight" }reason | Meaning | Retry? |
|---|---|---|
read_in_flight | Another check is already running — reads are single-flight per Mac | Yes, shortly |
connector_offline | The Mac is not connected | Yes, with backoff |
not_configured | Handle checking is not provisioned for this account | No — ask for it |
capability_unavailable | The Mac does not support handle checks | No |
deadline_exceeded | Apple did not answer in time | Yes |
session_closed | The session ended mid-read | Yes |
response_rejected | The response failed validation | Yes |
read_failed | The read failed on the host | Yes |
invalid_target | The connector refused the address grammar | No — fix the address |
Because reads are single-flight per Mac, the rate limit here is deliberately modest and
read_in_flight is common under concurrency. Check addresses serially, or cache the result —
reachability rarely changes.
invalid_target is the only reason that is about your address rather than the service, and you
should not normally be able to reach it: this endpoint validates the same grammar before the
request leaves it, so a malformed address gets 400 invalid_address instead. Seeing
invalid_target means the connector build disagrees with this service about what a valid handle
is. It is not a verdict that the address is off iMessage — do not cache it as one.
Errors
| Status | Code | Cause |
|---|---|---|
400 | invalid_address | Not E.164 or a lowercase email, or the body was not valid JSON |
401 | unauthenticated | No credential |
405 | method_not_allowed | Not a POST |
429 | rate_limited | 30 requests per minute |
503 | handle_check_unavailable | See the reason table above |