iMessage checker: check if a number supports iMessage
Use Blooio's contact capabilities API to check whether a phone number or email can receive iMessage before you route a workflow, trigger a CRM sequence, or fall back to SMS.
Get an API key
Create a Blooio API key from the dashboard and pass it as a Bearer token.
Check the contact
Call GET /contacts/{contactId}/capabilities with a URL-encoded phone number or email address.
Choose the channel
If imessage is true, prefer iMessage. If not, send through SMS fallback or route the contact differently.
Store the result
Save the last checked timestamp and expected protocol in your CRM so future sends can be segmented cleanly.
Overview
What an iMessage checker actually checks
An iMessage checker tells you whether a contact can receive native iMessage before you send. For businesses, that lets you segment contacts, personalize routing, and avoid treating every phone number like a generic SMS destination.
Blooio exposes this through the contact capabilities endpoint. You pass a phone number or email address, and the API returns the available protocols for that contact: iMessage, SMS, and FaceTime.
Endpoint
The API call
Send a GET request to /contacts/{contactId}/capabilities. The contact ID can be a phone number in E.164 format or an email address. URL-encode it before adding it to the path.
For example, +15551234567 becomes %2B15551234567.
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://backend.blooio.com/v2/api/contacts/%2B15551234567/capabilities"Response
How to read the result
{
"contact": "+15551234567",
"type": "phone",
"capabilities": {
"imessage": true,
"sms": true,
"facetime": true
},
"last_checked": 1703123457000
}The important field is capabilities.imessage. If it is true, you can route the contact through iMessage. If it is false but capabilities.sms is true, use SMS fallback.
- imessage - native blue-bubble messaging is available.
- sms - fallback SMS delivery is available.
- facetime - FaceTime capability is available for supported workflows.
Example
Build an iMessage checker in JavaScript
This example wraps the capabilities endpoint in a small helper you can call from a CRM sync, enrichment job, or lead intake workflow.
const BASE_URL = "https://backend.blooio.com/v2/api";
const API_KEY = process.env.BLOOIO_API_KEY;
async function checkIMessage(identifier) {
const contactId = encodeURIComponent(identifier);
const response = await fetch(
`${BASE_URL}/contacts/${contactId}/capabilities`,
{
headers: {
Authorization: `Bearer ${API_KEY}`,
},
}
);
if (!response.ok) {
throw new Error(`Capability check failed: ${response.status}`);
}
const result = await response.json();
return {
identifier: result.contact,
canReceiveIMessage: Boolean(result.capabilities?.imessage),
canReceiveSms: Boolean(result.capabilities?.sms),
canReceiveFaceTime: Boolean(result.capabilities?.facetime),
lastChecked: result.last_checked,
};
}
const capability = await checkIMessage("+15551234567");
console.log(capability.canReceiveIMessage ? "Use iMessage" : "Use SMS fallback");Example
Build an iMessage checker in Python
The same API works from Python. Store your Blooio API key in an environment variable and URL-encode the phone number before making the request.
import os
import requests
from urllib.parse import quote
BASE_URL = "https://backend.blooio.com/v2/api"
API_KEY = os.environ["BLOOIO_API_KEY"]
def check_imessage(identifier: str) -> dict:
contact_id = quote(identifier, safe="")
response = requests.get(
f"{BASE_URL}/contacts/{contact_id}/capabilities",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
response.raise_for_status()
data = response.json()
capabilities = data.get("capabilities", {})
return {
"identifier": data.get("contact"),
"can_receive_imessage": bool(capabilities.get("imessage")),
"can_receive_sms": bool(capabilities.get("sms")),
"can_receive_facetime": bool(capabilities.get("facetime")),
"last_checked": data.get("last_checked"),
}
result = check_imessage("+15551234567")
print("Use iMessage" if result["can_receive_imessage"] else "Use SMS fallback")Workflow
Use the checker before sending
In production, the checker is most useful when it feeds a routing decision. Check capabilities, save the expected protocol in your metadata, then send through the normal Blooio messages endpoint.
async function sendOnBestChannel(identifier, text) {
const contactId = encodeURIComponent(identifier);
const capability = await checkIMessage(identifier);
const response = await fetch(`${BASE_URL}/chats/${contactId}/messages`, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
text,
metadata: {
expected_protocol: capability.canReceiveIMessage ? "imessage" : "sms",
},
}),
});
if (!response.ok) {
throw new Error(`Message send failed: ${response.status}`);
}
return response.json();
}Best practices
When to check iMessage capability
At lead capture
Check capability as soon as a phone number or email enters your CRM so reps know the best channel before outreach.
Before campaign enrollment
Segment eligible contacts into iMessage-first workflows and route everyone else to SMS fallback or email.
After delivery changes
Refresh capability when a contact stops receiving messages, changes phone number, or has stale protocol data.
FAQ
iMessage checker FAQ
Can I check if a phone number has iMessage?
Does the checker work with email addresses?
Should I check capabilities before every send?
Is this the same as an Apple iMessage API?
Ready to add iMessage checks to your workflow?
Start with a free Blooio trial, check contact capabilities, then route messages through iMessage, SMS, or your CRM workflow.