Send an iMessage From Code: Python, Node.js and curl

export BASE=https://portal.zerosettle.io
export ZEROSETTLE_TOKEN='pt_mcp_…'   # from the console
curl -s -H "Authorization: Bearer $ZEROSETTLE_TOKEN" $BASE/api/imessage/line

curl -s -w '\nHTTP %{http_code}\n' -X POST \
  -H "Authorization: Bearer $ZEROSETTLE_TOKEN" -H 'Content-Type: application/json' \
  -d '{"to":"+18055559876","text":"Hi Sam, your order is ready for pickup. Reply here with any questions."}' \
  $BASE/api/imessage/send

{"ok": true, "status": "message_sent", "message": "…", "id": 43,
 "record": {"id": 43, "direction": "out", "handle": "+18055559876", "text": "Hi Sam, …",
            "status": "sent", "guid": null, "ts_ms": 1757400000000}}

# photo.jpg up to 5 MB; the body goes in a file because base64 is too long for an argument
printf '{"to":"+18055559876","image_format":"jpg","text":"Here it is","image_b64":"%s"}' \
  "$(base64 < photo.jpg | tr -d '\n')" > body.json
curl -s -X POST -H "Authorization: Bearer $ZEROSETTLE_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @body.json $BASE/api/imessage/send

# zerosettle.py: pip install requests
import os
import requests

BASE = os.environ.get("ZEROSETTLE_BASE_URL", "https://portal.zerosettle.io")
TOKEN = os.environ["ZEROSETTLE_TOKEN"]


class SendError(Exception):
    def __init__(self, status: int, error: dict):
        super().__init__(f"{status} {error.get('code')}: {error.get('message')}")
        self.status = status
        self.code = error.get("code")
        self.error = error


def send(to: str, **fields) -> dict:
    """POST /api/imessage/send. fields: text, image_b64 + image_format, reply_to, ..."""
    r = requests.post(f"{BASE}/api/imessage/send",
                      headers={"Authorization": f"Bearer {TOKEN}"},
                      json={"to": to, **fields}, timeout=120)
    try:
        body = r.json()
    except ValueError:  # a gateway page, not JSON: the send may still have gone
        raise SendError(r.status_code, {"code": "no_json", "message": r.text[:200]})
    if r.ok:
        return body
    raise SendError(r.status_code, body.get("error", {}))


if __name__ == "__main__":
    print(send("+18055559876", text="Hi from Python"))

// zerosettle.mjs: Node 18+, no packages
const BASE = process.env.ZEROSETTLE_BASE_URL ?? "https://portal.zerosettle.io";
const TOKEN = process.env.ZEROSETTLE_TOKEN;

export async function send(to, fields) {
  const r = await fetch(`${BASE}/api/imessage/send`, {
    method: "POST",
    headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" },
    body: JSON.stringify({ to, ...fields }),
    signal: AbortSignal.timeout(120_000),
  });
  const body = await r.json().catch(() => null); // null: not JSON, the send may still have gone
  if (r.ok && body) return body;
  const error = body?.error ?? { code: "no_json", message: `HTTP ${r.status}` };
  throw Object.assign(new Error(`${r.status} ${error.code}: ${error.message}`), { status: r.status, error });
}

// node -e 'import("./zerosettle.mjs").then(m => m.send("+18055559876", { text: "Hi from Node" })).then(console.log)'

curl -s -X PUT -H "Authorization: Bearer $ZEROSETTLE_TOKEN" -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/webhook"}' $BASE/api/imessage/webhook
# {"url": "https://example.com/webhook", "secret": "whsec_…", "typing_events": false,
#  "instant_typing": true, "usage": "Verify X-ZeroSettle-Signature with this secret. Shown once."}

POST https://example.com/webhook
Content-Type: application/json
User-Agent: ZeroSettle-iMessage/1
X-ZeroSettle-Event: message.received
X-ZeroSettle-Signature: t=1757400012,v1=3f0c…(64 hex chars)

{"event":"message.received","message":{"direction":"in","guid":"5A6F…","handle":"+18055559876","id":44,"status":"received","text":"hey!","ts_ms":1757400012000}}

# receiver.py: pip install fastapi uvicorn; run: uvicorn receiver:app --port 8100
import hashlib, hmac, json, os, time
from fastapi import FastAPI, Request, Response

SECRET = os.environ["ZEROSETTLE_WEBHOOK_SECRET"]
app = FastAPI()
seen: set[tuple[int, str]] = set()  # use your database in production


def verify(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        t, v1 = int(parts["t"]), parts["v1"]
    except Exception:
        return False
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)


@app.post("/webhook")
async def webhook(request: Request):
    raw = await request.body()  # the raw bytes, before any JSON parsing
    if not verify(SECRET, request.headers.get("X-ZeroSettle-Signature", ""), raw):
        return Response(status_code=401)
    payload = json.loads(raw)
    if payload["event"] != "message.received":
        return Response(status_code=200)  # message.sent echoes your own sends
    msg = payload["message"]
    key = (msg["id"], payload["event"])
    if key in seen:
        return Response(status_code=200)  # a retry of one already handled
    seen.add(key)
    print(msg["handle"], msg.get("text"))  # hand real work to a queue
    return Response(status_code=200)

// receiver.mjs: Node 18+, no packages; run: node receiver.mjs
import http from "node:http";
import crypto from "node:crypto";

const SECRET = process.env.ZEROSETTLE_WEBHOOK_SECRET;
const seen = new Set(); // use your database in production

function verify(secret, header, rawBody, tolerance = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "");
  if (!m) return false;
  const t = Number(m[1]);
  if (Math.abs(Date.now() / 1000 - t) > tolerance) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${t}.`).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}

http.createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/webhook") return res.writeHead(404).end();
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    if (!verify(SECRET, req.headers["x-zerosettle-signature"], raw)) return res.writeHead(401).end();
    const payload = JSON.parse(raw.toString("utf8"));
    res.writeHead(200).end(); // answer first, work after
    if (payload.event !== "message.received") return; // message.sent echoes your own sends
    const key = `${payload.message.id}:${payload.event}`;
    if (seen.has(key)) return; // a retry of one already handled
    seen.add(key);
    console.log(payload.message.handle, payload.message.text);
  });
}).listen(8100);

{"error": {"code": "new_contact_limit",
           "message": "This line can message at most 3 new contacts per 15m (3 already in this window). Existing conversations are not limited. Try again in 412 s.",
           "limit": 3, "window": "15m", "used": 3, "retry_after_s": 412},
 "detail": "This line can message at most 3 new contacts per 15m …"}

import time
from zerosettle import SendError, send


def deliver(to: str, **fields) -> dict:
    for attempt in range(5):
        try:
            return {"outcome": "sent", "id": send(to, **fields)["id"]}
        except SendError as e:
            if e.code == "line_busy":                              # 429
                time.sleep(2)
            elif e.code in ("phone_offline", "phone_timeout"):     # 503: 5 s, doubling
                time.sleep(5 * 2 ** attempt)
            elif e.code == "new_contact_limit":                    # 429: try again later
                return {"outcome": "retry_later", "after_s": e.error["retry_after_s"]}
            elif e.code == "awaiting_reply":                       # 403: 2 unanswered already
                return {"outcome": "wait_for_reply"}
            elif e.code == "attachment_before_reply":              # 403: text until they reply
                return {"outcome": "send_text_first", "kind": e.error.get("kind")}
            elif e.code in ("not_on_imessage", "recipient_opted_out"):  # 422 / 403
                return {"outcome": "do_not_contact", "code": e.code}
            else:                         # 402, 401, invalid_request, no_json: stop, tell a human
                raise
    return {"outcome": "gave_up"}


print(deliver("+18055559876", text="Hi Sam, your order is ready for pickup."))

// deliver.mjs
import { send } from "./zerosettle.mjs";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function deliver(to, fields) {
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      return { outcome: "sent", id: (await send(to, fields)).id };
    } catch (e) {
      const code = e.error?.code; // undefined for a timeout: the send may still have gone
      if (code === "line_busy") await sleep(2_000);                                       // 429
      else if (code === "phone_offline" || code === "phone_timeout") await sleep(5_000 * 2 ** attempt); // 503
      else if (code === "new_contact_limit") return { outcome: "retry_later", afterS: e.error.retry_after_s };
      else if (code === "awaiting_reply") return { outcome: "wait_for_reply" };            // 403
      else if (code === "attachment_before_reply") return { outcome: "send_text_first", kind: e.error.kind };
      else if (code === "not_on_imessage" || code === "recipient_opted_out") return { outcome: "do_not_contact", code };
      else throw e; // 402, 401, invalid_request, no_json, timeouts: stop, tell a human
    }
  }
  return { outcome: "gave_up" };
}