Addresses

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:

Need	Use
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:

Input	Accepted	Example
Full email address	Yes	`[email protected]`
E.164 phone number	Yes	`+15551234567`
Chat GUID	No	`any;-;[email protected]`
Display name	No	`Alice`
Short code or service number	No	`12345`

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:

Step	Action	Method
1	Check iMessage availability	`im.addresses.isIMessageAvailable(address)`
2	Create or resolve the chat	`im.chats.create([address])`
3	Send the message	`im.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 value	Meaning
`true`	Apple currently reports that this address can be reached over iMessage
`false`	The 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:

Field	Type	Meaning
`address`	`string`	The server’s stored form of the email address or E.164 phone number
`country`	`string \| null`	ISO 3166-1 alpha-2 country code, or `null` when unknown
`services`	`ChatServiceType[]`	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 value	Meaning
`true`	Notifications from this address may currently be silenced by Focus
`false`	No 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

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

Advanced Kits

Opensource Kits

Utilities

Input Format

Common Flow

Check iMessage Availability

Get Address Details

Check Focus Status

Next Steps

​Input Format

​Common Flow

​Check iMessage Availability

​Get Address Details

​Check Focus Status

​Next Steps

Input Format

Common Flow

Check iMessage Availability

Get Address Details

Check Focus Status

Next Steps