How do I send an iMessage programmatically?

# Illustrative shape. Endpoints and field names differ per vendor —
# always check the provider's live docs.
curl -X POST https://api.example-provider.com/v1/messages \
  -H "Authorization: Bearer $IMESSAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "text": "Your appointment is confirmed for Tuesday at 2pm. Reply STOP to opt out.",
    "send_style": "default"
  }'

// Write to your own interface from day one. When you change providers —
// and in this category you might — this is the only file that moves.
type SendResult = { id: string; channel: "imessage" | "sms" };
 
export async function send(to: string, text: string): Promise<SendResult> {
  const res = await fetch("https://api.example-provider.com/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.IMESSAGE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ to, text }),
  });
 
  if (!res.ok) {
    // Treat 429 and 5xx as retryable; 4xx as a bug in your call.
    throw new Error(`send failed: ${res.status} ${await res.text()}`);
  }
 
  const data = await res.json();
  return { id: data.id, channel: data.channel ?? "imessage" };
}

# The bridge runs on your Mac; the API is yours, on your network.
curl -X POST "http://your-mac.local:1234/api/v1/message/text" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "'"$BRIDGE_PASSWORD"'",
    "chatGuid": "iMessage;-;+15551234567",
    "message": "Your appointment is confirmed for Tuesday at 2pm."
  }'

import { execFile } from "node:child_process";
import { promisify } from "node:util";
 
const run = promisify(execFile);
 
export async function sendLocal(phone: string, text: string) {
  // Passing values as argv keeps quotes and apostrophes from breaking
  // the script — never string-concatenate user text into AppleScript.
  const script = `
    on run argv
      set phone to item 1 of argv
      set msg to item 2 of argv
      tell application "Messages"
        set svc to 1st account whose service type = iMessage
        send msg to participant phone of svc
      end tell
    end run`;
 
  await run("osascript", ["-e", script, phone, text]);
}