imessage

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:

1. On iPhone: Settings → Messages → Text Message Forwarding
2. 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)