iMessage Integration

Send and read iMessages/SMS using the imsg CLI tool on macOS.

Setup

1. Build the imsg CLI

Clone and build the tool:

git clone https://github.com/letta-ai/imsg.git ~/repos/imsg cd ~/repos/imsg swift build -c release

The binary will be at ~/repos/imsg/.build/release/imsg (or use the pre-built binary if available at ~/repos/imsg/bin/imsg ).

2. Grant Permissions

Required macOS permissions (System Settings → Privacy & Security):

Permission Location Required For

Full Disk Access Privacy & Security → Full Disk Access Reading message history

Automation Privacy & Security → Automation Sending messages via Messages.app

3. Enable SMS Relay (Optional)

To send SMS (green bubbles) to non-iMessage users:

• On iPhone: Settings → Messages → Text Message Forwarding

• Enable forwarding to your Mac

Commands

List Recent Chats

imsg chats --limit 10 imsg chats --limit 10 --json

Output format: [chat_id] (identifier) last=timestamp

View Chat History

View last 20 messages in a chat

imsg history --chat-id <id> --limit 20

With attachments metadata

imsg history --chat-id <id> --limit 20 --attachments

Filter by date

imsg history --chat-id <id> --start 2026-01-01T00:00:00Z --json

Send a Message

Send to phone number

imsg send --to "+15555555555" --text "Hello!"

Send with attachment

imsg send --to "+15555555555" --text "Here's the file" --file /path/to/file.jpg

Force iMessage or SMS

imsg send --to "+15555555555" --text "Hi" --service imessage imsg send --to "+15555555555" --text "Hi" --service sms

Send to existing chat by ID

imsg send --chat-id 86 --text "Hello!"

Watch for New Messages

imsg watch --chat-id <id> --debounce 250ms

Best Practices

Phone Number Format

• Use E.164 format: +1XXXXXXXXXX for US numbers

• Include country code for international

SMS vs iMessage

• iMessage (blue bubble): Default for Apple device users, free

• SMS (green bubble): Requires iPhone relay, may have carrier charges

• Use --service sms when recipient doesn't have iMessage

Message Etiquette for Agents

• Be concise - Keep messages short and clear

• Be human - Write naturally, not robotically

• Identify context - If following up, reference previous conversation

• Respect timing - Avoid early morning/late night messages

Common Use Cases

Scheduling Services

imsg send --to "+14155551234" --text "Hi! Do you have availability this Saturday for a cleaning?"

Following Up

imsg send --to "+14155551234" --text "Just wanted to follow up on my earlier message. Let me know when you have a chance!"

Confirming Appointments

imsg send --to "+14155551234" --text "Confirming our appointment for Saturday at 10am. See you then!"

Troubleshooting

Issue Solution

"not authorized" error Grant Automation permission to terminal

Can't read messages Grant Full Disk Access to terminal

SMS not sending Enable Text Message Forwarding on iPhone

Message stuck sending Check Messages.app is signed in and working

Technical Notes

• Uses AppleScript for sending (no private APIs)

• Read operations are read-only on the Messages SQLite database

• Requires macOS 14+ with Messages.app configured

• Binary location: ~/repos/imsg/bin/imsg (adjust path as needed)