Skip to main content
im.addresses works with contact addresses before they become chats. An address is a full email address or an E.164 phone number. It is not a chat GUID, a contact display name, or a short code. Use this namespace when you need to answer one of these questions:
NeedUse
Can this email or phone number currently receive iMessage?im.addresses.isIMessageAvailable(address)
What address, country, and delivery services does the server have on record?im.addresses.get(address)
Is this recipient currently silencing notifications with Focus?im.addresses.isFocusSilenced(address)
im.addresses only checks address-level state. After you have a chat.guid, send, edit, unsend, reply, and notify through the messages API.

​
Input Format

Every im.addresses method accepts the same address argument:
InputAcceptedExample
Full email addressYes[email protected]
E.164 phone numberYes+15551234567
Chat GUIDNoany;-;[email protected]
Display nameNoAlice
Short code or service numberNo12345
Phone numbers must be E.164: include the country code, start with +, and omit spaces, parentheses, and dashes.

​
Common Flow

Before you create a new chat, the most common preflight check is iMessage availability:
StepActionMethod
1Check iMessage availabilityim.addresses.isIMessageAvailable(address)
2Create or resolve the chatim.chats.create([address])
3Send the messageim.messages.sendText(chat.guid, text)
const address = "[email protected]";

const available = await im.addresses.isIMessageAvailable(address);

if (!available) {
  throw new Error(`${address} is not available on iMessage`);
}

const { chat } = await im.chats.create([address]);
await im.messages.sendText(chat.guid, "Hello");
isIMessageAvailable(...) is a check only. It does not create a chat. im.chats.create(...) creates or resolves the chat and returns the chat.guid used by message APIs.

​
Check iMessage Availability

const available = await im.addresses.isIMessageAvailable("+15551234567");
Returns boolean:
Return valueMeaning
trueApple currently reports that this address can be reached over iMessage
falseThe address is unavailable, or availability could not be confirmed
Use this before starting a new conversation when you want to avoid sending iMessage traffic to an address that is clearly unreachable.
Availability is a live Apple lookup. true means it is reasonable to continue creating a chat and sending a message, but it does not guarantee that the later send will succeed. Network conditions, account state, or Apple service state can still change.

​
Get Address Details

const info = await im.addresses.get("[email protected]");
console.log(info.address, info.country, info.services);
Returns MultiServiceAddressInfo:
FieldTypeMeaning
addressstringThe server’s stored form of the email address or E.164 phone number
countrystring | nullISO 3166-1 alpha-2 country code, or null when unknown
servicesChatServiceType[]Available services: "iMessage", "SMS", "RCS", or "unknown"
get(...) throws NotFoundError when the server has no record for the address.
If you only need to know whether the address can use iMessage, call isIMessageAvailable(...). Use get(...) when you need address details such as country or available services.

​
Check Focus Status

const silenced = await im.addresses.isFocusSilenced("[email protected]");
Returns boolean:
Return valueMeaning
trueNotifications from this address may currently be silenced by Focus
falseNo Focus silence state was detected
Focus is a live Apple state, not a long-term recipient preference. This method tells you whether the recipient may be silencing notifications right now. To trigger Apple’s “Notify Anyway” action after sending, use im.messages.notifySilenced(...) with chat.guid and message.guid.

​
Next Steps

  1. Chats — create a chat from an address and get chat.guid
  2. Messages — send text, attachments, and replies with chat.guid
  3. Error Handling — handle NotFoundError, retries, and structured error context