Check iMessage availability

Overview

POST /check-imessage tells you whether a single address can receive an iMessage, before you spend a send on it. You pass one phone number or email address. You get back two booleans: imessage and rcs. POST /check-imessage-bulk does the same thing for up to 100 addresses in one call and returns a result for each one. Both endpoints are read only. Nothing is sent to the address, and the person on the other end sees nothing. They use POST instead of GET so contact data stays in the request body and never lands in a URL, a proxy log, or a browser history. Base URL for every BlueReacher endpoint:

https://api.bluereacher.com/functions/v1/

Why check before you send

Checking first is the difference between a clean campaign and a broken one.

You stop burning sends. An iMessage aimed at an Android number cannot be delivered as an iMessage. Check first, and you route that contact to RCS or SMS instead of watching the send fail.
Your reply rate stays honest. Undeliverable addresses sit in your denominator and drag every campaign metric down. Filter them out before launch and your numbers describe real conversations.
Your line stays healthy. Repeatedly pushing traffic at addresses that cannot receive it is a bad pattern. BlueReacher gives you dedicated iMessage lines, managed for you, with no A2P registration required, and the fastest way to protect that line is to only message people who can actually receive the message.
Your list stays current. People switch phones. A number that was on iMessage in March can be on Android in July. A bulk check the morning of a send catches that.
Checks are free. Availability checks are not billed as messages and do not count against your message volume. Only rate limits apply.

The practical pattern: run check-imessage-bulk over your list right before a campaign, split the results into iMessage, RCS, and SMS groups, then send each group on the channel it can receive.

Authentication

Every request needs your API key in the Authorization header and a JSON content type:

Authorization: Bearer bluereacher_your_api_key
Content-Type: application/json

Keys are workspace scoped and are created in your BlueReacher dashboard. Call these endpoints from your server. A key shipped in browser or mobile code can be read by anyone who opens the network tab.

Check one address

POST https://api.bluereacher.com/functions/v1/check-imessage Looks up a single address and returns its channel availability.

Request fields

Field	Type	Required	Description
`to`	string	Yes	The address to check. A phone number in E.164 format (`+15551234567`) or an email address used as an Apple ID (`ana@example.com`). Numbers without a `+` and country code are rejected with `invalid_address`.

No other fields are accepted. Unknown fields in the body are ignored.

Example request

curl -X POST https://api.bluereacher.com/functions/v1/check-imessage \
  -H "Authorization: Bearer bluereacher_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567"
  }'

Response fields

Field	Type	Description
`address`	string	The address that was checked, normalized. Phone numbers come back in E.164. Emails come back lowercased.
`imessage`	boolean	`true` if the address can receive an iMessage. `false` if it cannot.
`rcs`	boolean	`true` if the address can receive RCS. Always `false` for email addresses.
`checked_at`	string	ISO 8601 UTC timestamp of when this result was determined. If it is older than your request, you received a cached result. See Freshness and caching.

Successful lookups return 200 OK.

Example response

{
  "address": "+15551234567",
  "imessage": true,
  "rcs": false,
  "checked_at": "2026-07-24T16:42:09Z"
}

A number that is not on iMessage but can take RCS:

{
  "address": "+15559876543",
  "imessage": false,
  "rcs": true,
  "checked_at": "2026-07-24T16:42:11Z"
}

Error notes

400 with invalid_address is the one you will hit most. It almost always means the number was not in E.164. Normalize before you call: strip spaces, parentheses, and dashes, then add the country code. Full list in Errors.

Check up to 100 addresses

POST https://api.bluereacher.com/functions/v1/check-imessage-bulk Checks a batch of addresses in one call. Use this for list hygiene and pre-campaign segmentation. It is roughly ten times more throughput per minute than looping the single endpoint.

Request fields

Field	Type	Required	Description
`addresses`	array of strings	Yes	The addresses to check. Same format rules as `to`. Minimum 1, maximum 100 per call. An empty array returns `400 invalid_request`. More than 100 returns `400 too_many_addresses`.

Duplicates are collapsed and checked once. Results come back in the order each address first appears in your array, so you can zip them against your input after deduping.

Example request

curl -X POST https://api.bluereacher.com/functions/v1/check-imessage-bulk \
  -H "Authorization: Bearer bluereacher_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "+15551234567",
      "+15559876543",
      "ana@example.com",
      "5551112222"
    ]
  }'

Response fields

Field	Type	Description
`count`	integer	Number of results returned. Equals the number of unique addresses in your request.
`results`	array of objects	One object per unique address, in first-appearance order.
`results[].address`	string	The address that was checked, normalized. Addresses that failed validation are echoed back exactly as you sent them.
`results[].imessage`	boolean or null	`true` or `false` for a successful lookup. `null` when that address has an `error`.
`results[].rcs`	boolean or null	`true` or `false` for a successful lookup. `null` when that address has an `error`.
`results[].checked_at`	string or null	ISO 8601 UTC timestamp of the result. `null` when that address has an `error`.
`results[].error`	object or null	Present only when this address could not be checked. Contains `code` and `message`.

A well formed request returns 200 OK even when some addresses fail. Per-address problems live inside results, not in the HTTP status. Check results[].error on every item. Per-address error codes:

Code	Meaning	What to do
`invalid_address`	Not a valid E.164 number or email address.	Fix the format in your list. Retrying will not help.
`lookup_failed`	The availability lookup did not complete for this address.	Retry this address on its own after a few seconds.

Example response

{
  "count": 4,
  "results": [
    {
      "address": "+15551234567",
      "imessage": true,
      "rcs": false,
      "checked_at": "2026-07-24T16:44:02Z",
      "error": null
    },
    {
      "address": "+15559876543",
      "imessage": false,
      "rcs": true,
      "checked_at": "2026-07-24T16:44:02Z",
      "error": null
    },
    {
      "address": "ana@example.com",
      "imessage": true,
      "rcs": false,
      "checked_at": "2026-07-24T16:44:02Z",
      "error": null
    },
    {
      "address": "5551112222",
      "imessage": null,
      "rcs": null,
      "checked_at": null,
      "error": {
        "code": "invalid_address",
        "message": "Phone numbers must be in E.164 format, for example +15551112222."
      }
    }
  ]
}

Error notes

The whole call fails with a 4xx only when the request itself is wrong: bad JSON, missing addresses, an empty array, or more than 100 entries. Anything address-specific comes back inside results with a 200.

Splitting a larger list

Lists longer than 100 have to be chunked. Both examples below also handle a 429 by waiting the number of seconds in the Retry-After header, then retrying the same chunk.

const URL = "https://api.bluereacher.com/functions/v1/check-imessage-bulk";
const HEADERS = {
  "Authorization": "Bearer bluereacher_your_api_key",
  "Content-Type": "application/json"
};

async function checkAll(addresses) {
  const results = [];

  for (let i = 0; i < addresses.length; i += 100) {
    const chunk = addresses.slice(i, i + 100);
    const res = await fetch(URL, {
      method: "POST",
      headers: HEADERS,
      body: JSON.stringify({ addresses: chunk })
    });

    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") || 5);
      await new Promise(r => setTimeout(r, wait * 1000));
      i -= 100; // step back so the loop retries this same chunk
      continue;
    }

    if (!res.ok) {
      throw new Error(`check-imessage-bulk failed: ${res.status}`);
    }

    const data = await res.json();
    results.push(...data.results);
  }

  return results;
}

// Split the results into send groups
const checked = await checkAll(myList);
const imessage = checked.filter(r => r.imessage === true);
const rcs = checked.filter(r => r.imessage === false && r.rcs === true);
const sms = checked.filter(r => r.imessage === false && r.rcs === false);

import time
import requests

URL = "https://api.bluereacher.com/functions/v1/check-imessage-bulk"
HEADERS = {
    "Authorization": "Bearer bluereacher_your_api_key",
    "Content-Type": "application/json",
}

def check_all(addresses):
    results = []

    for i in range(0, len(addresses), 100):
        chunk = addresses[i:i + 100]

        while True:
            r = requests.post(URL, headers=HEADERS, json={"addresses": chunk})

            if r.status_code == 429:
                time.sleep(int(r.headers.get("Retry-After", 5)))
                continue

            r.raise_for_status()
            results.extend(r.json()["results"])
            break

    return results

Picking a channel from the result

The channel field on a send accepts "imessage", "rcs", or "sms". Map the check straight onto it:

`imessage`	`rcs`	Send with
`true`	anything	`"imessage"`
`false`	`true`	`"rcs"`
`false`	`false`	`"sms"`

Skip any result where error is not null. You do not know that contact’s availability, so do not guess a channel for it.

Freshness and caching

Results are cached for 24 hours per address. A repeat check inside that window returns the stored result, and checked_at shows the original lookup time rather than the time of your call. Compare checked_at to now if you need to know how fresh a result is. Cached responses still count against your rate limit. Two habits that keep this accurate:

Check within 24 hours of sending, not weeks ahead. Availability changes when people change phones.
Store imessage, rcs, and checked_at on your contact record. Re-check anything older than 24 hours instead of trusting a stale flag.

Rate limits

Limits are per API key, counted across your whole workspace, over a rolling 60 second window.

Endpoint	Limit	Addresses per minute
`POST /check-imessage`	600 requests per minute	600
`POST /check-imessage-bulk`	60 requests per minute	6,000

Batching is the cheaper path by a wide margin. Use check-imessage-bulk for anything over a handful of addresses and save the single endpoint for real time lookups, like a form submission or a CRM record opening. Every response carries the current state of your limit:

Header	Description
`X-RateLimit-Limit`	Requests allowed in the window for this endpoint.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Reset`	Unix timestamp in seconds when the window resets.
`Retry-After`	Seconds to wait before retrying. Sent only on a `429`.

Going over returns 429 Too Many Requests:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for check-imessage-bulk. Retry after 12 seconds."
  }
}

Wait the number of seconds in Retry-After, then retry the same request. Both endpoints are read only and have no side effects, so retrying is always safe. If you are running a large list check on a schedule, watch X-RateLimit-Remaining and slow down before you hit zero rather than driving into 429s.

Errors

Errors use one shape across the whole API:

{
  "error": {
    "code": "invalid_address",
    "message": "Phone numbers must be in E.164 format, for example +15551234567."
  }
}

Status	Code	Meaning	Fix
`400`	`invalid_request`	Body is not valid JSON, `to` is missing, or `addresses` is missing or empty.	Check the payload against the request field table above.
`400`	`invalid_address`	`to` is not a valid E.164 number or email address.	Normalize the address. On the bulk endpoint this appears per address inside `results`, not as a `400`.
`400`	`too_many_addresses`	More than 100 entries in `addresses`.	Split into chunks of 100.
`401`	`unauthorized`	API key missing, malformed, or revoked.	Send `Authorization: Bearer bluereacher_your_api_key` with a current key.
`403`	`account_inactive`	Key is valid but the workspace is suspended or not yet provisioned.	Contact BlueReacher support.
`405`	`method_not_allowed`	Request used a method other than `POST`.	Use `POST`.
`415`	`unsupported_media_type`	`Content-Type` was not `application/json`.	Set the header.
`429`	`rate_limited`	Rate limit exceeded.	Wait `Retry-After` seconds and retry.
`500`	`internal_error`	Something broke on our side.	Retry once after a short backoff. If it persists, contact support.
`503`	`lookup_unavailable`	The availability lookup is temporarily unavailable.	Retry with exponential backoff. Do not treat this as `imessage: false`.

One rule worth writing into your code: never read an error as a negative result. imessage: false means the address cannot receive iMessage. An error means you do not know yet. Retry or hold the contact back instead of downgrading them to SMS on bad information.

Messages

Contacts and lines

Automation

Check iMessage availability

Overview

Why check before you send

Authentication

Check one address

Request fields

Example request

Response fields

Example response

Error notes

Check up to 100 addresses

Request fields

Example request

Response fields

Example response

Error notes

Splitting a larger list

Picking a channel from the result

Freshness and caching

Rate limits

Errors

​Overview

​Why check before you send

​Authentication

​Check one address

​Request fields

​Example request

​Response fields

​Example response

​Error notes

​Check up to 100 addresses

​Request fields

​Example request

​Response fields

​Example response

​Error notes

​Splitting a larger list

​Picking a channel from the result

​Freshness and caching

​Rate limits

​Errors

Overview

Why check before you send

Authentication

Check one address

Request fields

Example request

Response fields

Example response

Error notes

Check up to 100 addresses

Request fields

Example request

Response fields

Example response

Error notes

Splitting a larger list

Picking a channel from the result

Freshness and caching

Rate limits

Errors