Get Messages - Advanced iMessage Kit

getMessage

Retrieve a single message by its GUID.

Method Signature

await sdk.messages.getMessage(guid: string, options?: { with?: string[] }): Promise<MessageResponse>

Parameters

guid

string

required

The unique identifier of the message to retrieve

options.with

string[]

Array of related entities to include in the responseOptions:

"handle" - Include sender/recipient information
"chats" - Include chat information
"attachments" - Include attachment data

Example

const message = await sdk.messages.getMessage(
  "iMessage;-;[email protected];12345",
  { with: ["handle", "attachments"] }
);

console.log(`Message: ${message.text}`);
console.log(`From: ${message.handle?.address}`);
console.log(`Attachments: ${message.attachments?.length || 0}`);

getMessages

Query and retrieve multiple messages with filtering and pagination.

Method Signature

await sdk.messages.getMessages(options?: {
  chatGuid?: string;
  offset?: number;
  limit?: number;
  sort?: "ASC" | "DESC";
  before?: number;
  after?: number;
  with?: string[];
}): Promise<MessageResponse[]>

Parameters

chatGuid

string

Filter messages to a specific chat

offset

number

default:"0"

Number of messages to skip (for pagination)

limit

number

default:"100"

Maximum number of messages to return

sort

'ASC' | 'DESC'

default:"DESC"

Sort order by creation date

"ASC" - Oldest first
"DESC" - Newest first

before

number

Only return messages created before this timestamp (milliseconds since epoch)

after

number

Only return messages created after this timestamp (milliseconds since epoch)

with

string[]

Array of related entities to include. Options: "handle", "chats", "attachments"

Examples

Get Recent Messages from a Chat

const messages = await sdk.messages.getMessages({
  chatGuid: "iMessage;-;[email protected]",
  limit: 50,
  sort: "DESC"
});

console.log(`Retrieved ${messages.length} messages`);
messages.forEach(msg => {
  console.log(`[${new Date(msg.dateCreated)}] ${msg.text}`);
});

Paginate Through Messages

const pageSize = 25;
let offset = 0;
let hasMore = true;

while (hasMore) {
  const messages = await sdk.messages.getMessages({
    chatGuid: "iMessage;-;[email protected]",
    offset,
    limit: pageSize,
    sort: "DESC"
  });
  
  console.log(`Page ${offset / pageSize + 1}: ${messages.length} messages`);
  
  hasMore = messages.length === pageSize;
  offset += pageSize;
}

Get Messages from Last 24 Hours

const oneDayAgo = Date.now() - (24 * 60 * 60 * 1000);

const recentMessages = await sdk.messages.getMessages({
  after: oneDayAgo,
  with: ["handle"]
});

console.log(`${recentMessages.length} messages in the last 24 hours`);

Get Messages in Date Range

const startDate = new Date("2026-03-01").getTime();
const endDate = new Date("2026-03-02").getTime();

const messages = await sdk.messages.getMessages({
  after: startDate,
  before: endDate,
  chatGuid: "iMessage;-;[email protected]"
});

console.log(`${messages.length} messages on March 1st, 2026`);

searchMessages

Search for messages containing specific text.

Method Signature

await sdk.messages.searchMessages(options: {
  query: string;
  chatGuid?: string;
  offset?: number;
  limit?: number;
  sort?: "ASC" | "DESC";
  before?: number;
  after?: number;
}): Promise<MessageResponse[]>

On macOS 13+, search uses Spotlight API with token-based matching. Word boundaries matter: “Hello” matches “Hello world” but “Hell” does not match “Hello”.

Parameters

query

string

required

Search query text. Cannot be empty. Uses token-based matching on macOS 13+.

chatGuid

string

Limit search to a specific chat

offset

number

default:"0"

Number of results to skip

limit

number

default:"100"

Maximum number of results to return

sort

'ASC' | 'DESC'

default:"DESC"

Sort order by creation date

before

number

Only search messages before this timestamp

after

number

Only search messages after this timestamp

Examples

Basic Search

const results = await sdk.messages.searchMessages({
  query: "meeting",
  limit: 20
});

console.log(`Found ${results.length} messages containing "meeting"`);

Search Within a Chat

const results = await sdk.messages.searchMessages({
  query: "project deadline",
  chatGuid: "iMessage;-;[email protected]"
});

results.forEach(msg => {
  console.log(`${msg.text} - ${new Date(msg.dateCreated).toLocaleDateString()}`);
});

Search with Date Range

const lastWeek = Date.now() - (7 * 24 * 60 * 60 * 1000);

const results = await sdk.messages.searchMessages({
  query: "invoice",
  after: lastWeek,
  sort: "DESC"
});

console.log(`${results.length} messages about invoices in the last week`);

getMessageCount

Get the total count of messages matching specific criteria.

Method Signature

await sdk.messages.getMessageCount(options?: {
  after?: number;
  before?: number;
  chatGuid?: string;
  minRowId?: number;
  maxRowId?: number;
}): Promise<number>

Parameters

after

number

Count messages created after this timestamp

before

number

Count messages created before this timestamp

chatGuid

string

Count messages in a specific chat

minRowId

number

Minimum database row ID

maxRowId

number

Maximum database row ID

Examples

Count All Messages

const totalMessages = await sdk.messages.getMessageCount();
console.log(`Total messages: ${totalMessages}`);

Count Messages in Chat

const count = await sdk.messages.getMessageCount({
  chatGuid: "iMessage;-;[email protected]"
});
console.log(`Messages in chat: ${count}`);

Count Recent Messages

const yesterday = Date.now() - (24 * 60 * 60 * 1000);
const count = await sdk.messages.getMessageCount({
  after: yesterday
});
console.log(`Messages in last 24 hours: ${count}`);

Response Format

All methods (except getMessageCount) return MessageResponse objects with the following key fields:

guid

string

Unique message identifier

text

string

Message text content

dateCreated

number

Creation timestamp (milliseconds since epoch)

dateRead

number | null

Read timestamp, or null if unread

dateDelivered

number | null

Delivery timestamp, or null if not delivered

isFromMe

boolean

Whether the message was sent by you

handle

HandleResponse | null

Sender/recipient information (if included with with parameter)

chats

ChatResponse[]

Associated chats (if included with with parameter)

attachments

AttachmentResponse[]

Attached files (if included with with parameter)

dateEdited

number | null

Last edit timestamp, or null if never edited

sendMessage - Send a new message
editMessage - Edit an existing message
unsendMessage - Unsend a message

getUpdatedMessageCount

Get the count of messages that have been updated (edited, reacted to, etc.).

Method Signature

await sdk.messages.getUpdatedMessageCount(options?: {
  after?: number;
  before?: number;
  chatGuid?: string;
  minRowId?: number;
  maxRowId?: number;
}): Promise<number>

Parameters

after

number

Count updated messages after this timestamp

before

number

Count updated messages before this timestamp

chatGuid

string

Count updated messages in a specific chat

minRowId

number

Minimum database row ID

maxRowId

number

Maximum database row ID

Example

const updatedCount = await sdk.messages.getUpdatedMessageCount({
  after: Date.now() - (24 * 60 * 60 * 1000)
});
console.log(`Messages updated in last 24 hours: ${updatedCount}`);

getSentMessageCount

Get the count of messages you have sent.

Method Signature

await sdk.messages.getSentMessageCount(options?: {
  after?: number;
  before?: number;
  chatGuid?: string;
  minRowId?: number;
  maxRowId?: number;
}): Promise<number>

Parameters

after

number

Count sent messages after this timestamp

before

number

Count sent messages before this timestamp

chatGuid

string

Count sent messages in a specific chat

minRowId

number

Minimum database row ID

maxRowId

number

Maximum database row ID

Example

const sentCount = await sdk.messages.getSentMessageCount();
console.log(`Total messages sent: ${sentCount}`);

// Count sent messages in a specific chat
const chatSentCount = await sdk.messages.getSentMessageCount({
  chatGuid: "iMessage;-;[email protected]"
});

notifyMessage

Trigger a notification for a specific message.

Method Signature

await sdk.messages.notifyMessage(guid: string): Promise<void>

Parameters

guid

string

required

The unique identifier of the message to notify

Example

await sdk.messages.notifyMessage("message-guid-here");

getEmbeddedMedia

Get embedded media (rich link preview, inline content) for a message.

Method Signature

await sdk.messages.getEmbeddedMedia(guid: string): Promise<{
  path?: string;
  data?: string;
}>

Parameters

guid

string

required

The unique identifier of the message

Response

path

string

File path to the embedded media (if stored as file)

data

string

Base64-encoded embedded media data (if stored inline)

Example

const media = await sdk.messages.getEmbeddedMedia("message-guid");

if (media.path) {
  console.log(`Media file: ${media.path}`);
}

if (media.data) {
  // Handle base64 data
  const buffer = Buffer.from(media.data, 'base64');
}

Client

Messages

Chats

Attachments

Contacts & Handles

Scheduled Messages

Polls

FaceTime

iCloud & Find My

Server

Events

Utilities

​getMessage

​Method Signature

​Parameters

​Example

​getMessages

​Method Signature

​Parameters

​Examples

​Get Recent Messages from a Chat

​Paginate Through Messages

​Get Messages from Last 24 Hours

​Get Messages in Date Range

​searchMessages

​Method Signature

​Parameters

​Examples

​Basic Search

​Search Within a Chat

​Search with Date Range

​getMessageCount

​Method Signature

​Parameters

​Examples

​Count All Messages

​Count Messages in Chat

​Count Recent Messages

​Response Format

​Related Methods

​getUpdatedMessageCount

​Method Signature

​Parameters

​Example

​getSentMessageCount

​Method Signature

​Parameters

​Example

​notifyMessage

​Method Signature

​Parameters

​Example

​getEmbeddedMedia

​Method Signature

​Parameters

​Response

​Example

Build docs developers (and LLMs) love

getMessage

Method Signature

Parameters

Example

getMessages

Method Signature

Parameters

Examples

Get Recent Messages from a Chat

Paginate Through Messages

Get Messages from Last 24 Hours

Get Messages in Date Range

searchMessages

Method Signature

Parameters

Examples

Basic Search

Search Within a Chat

Search with Date Range

getMessageCount

Method Signature

Parameters

Examples

Count All Messages

Count Messages in Chat

Count Recent Messages

Response Format

Related Methods

getUpdatedMessageCount

Method Signature

Parameters

Example

getSentMessageCount

Method Signature

Parameters

Example

notifyMessage

Method Signature

Parameters

Example

getEmbeddedMedia

Method Signature

Parameters

Response

Example