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. Every reason is retry-later except
invalid_target, which is a definitive answer that the address was refused.
{ "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 — contact Mapier |
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 | Apple refused the address | No — treat as unreachable |
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.
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 |