Documentation Index
Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
Use this file to discover all available pages before exploring further.
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.
Every im.addresses method accepts the same address argument:
| Input | Accepted | Example |
|---|
| Full email address | Yes | alice@example.com |
| E.164 phone number | Yes | +15551234567 |
| Chat GUID | No | any;-;alice@example.com |
| Display name | No | Alice |
| Short code or service number | No | 12345 |
+, 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 = "alice@example.com";
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");
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 |
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("alice@example.com");
console.log(info.address, info.country, info.services);
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("alice@example.com");
boolean:
| Return value | Meaning |
|---|
true | Notifications from this address may currently be silenced by Focus |
false | No Focus silence state was detected |
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
