iMessage API delivery status, webhook retries and latency, explained

What does “sent” mean in ZeroSettle’s API?

In ZeroSettle’s API, “sent” means the line handed the message to Apple, and that is the last status the API reports. The send call itself blocks until that hand-off, then returns "status": "message_sent" with the stored message id.

Your own sends come back to your webhook as message.sent, so an auto-responder should react only to message.received or it will answer itself.

Why are there no read receipts in the API?

ZeroSettle’s API has no event or field for “delivered to the recipient” or “read”, so no workflow should depend on one. ZeroSettle’s iMessage API Terms (section 7) say why such signals are weak evidence either way:

Delivery of a message does not guarantee that it was read, and the absence of a receipt does not mean a message was not delivered.

ZeroSettle iMessage API Terms, section 7

The same section adds that outputs including “message status, delivery and read receipts, typing indicators” “may be delayed, incomplete, or inaccurate,” and section 2 states that “delivery of any particular message or feature is not guaranteed.” A 200 from the send call is therefore not proof the customer got the message. The dependable signal of attention is an answer: a reply arrives as message.received, and a tapback as reaction.received. Ask for one when it matters. The on-call alert pattern uses a tapback as the acknowledgment and escalates when none arrives.

How fast is a send?

A ZeroSettle send returns once the line has handed the message to Apple: “normally 2–5 seconds and at most about 75 for a text (about 105 for a voice message or photo, which ZeroSettle converts first).” Set your HTTP client timeout above those ceilings; the docs’ examples use 90 seconds for a text and 120 for a photo or voice message.

• One send at a time per line. Concurrent sends “queue behind each other and surface as line_busy after ~12 s of waiting.” Retry after 2 seconds. If order matters, send from one worker per line.
• Typing is ordered with sends. POST /api/imessage/typing (ttl_s 1–60, default 25) shares the send queue, so the bubble shows before the text, and your next send to that person clears it. It is not stored, not billed and never a new contact, and works only with someone you already have a conversation with (otherwise 409 no_conversation).

The first send, end to end, is in how to send an iMessage from code without a Mac.

How fast does a reply reach you?

A customer’s text reaches your ZeroSettle webhook about 1–2 seconds after the line receives it. In the docs’ words, “Inbound is pushed; nothing polls for it, so inbound never delays a send.”

For an auto-reply, the documented figures add up to about 3–7 seconds from the customer’s text reaching the line to your answer leaving it (1–2 s inbound plus a 2–5 s send), plus your own lookup or model call. When that work takes more than a couple of seconds, raise the typing bubble first.

What happens when your webhook is down?

ZeroSettle waits 10 seconds for a 2xx; on a non-2xx or a timeout it retries 3 more times, after 1 s, 5 s and 20 s, then records the failure. Redirects are not followed, so a URL that answers with a redirect fails the same way.

Network time adds a little to each figure.

So a receiver that refuses connections for more than about 26 seconds, during a deploy for example, can miss the webhook for a message that arrived at the start of that gap. The message itself is still stored. GET /api/imessage/line shows last_delivery (ok, status_code, error, attempts, at), and the live stream sends a delivery event with the same fields. Recover by paging forward with after_id from the cursor your last backfill saved, skipping ids your webhook already handled, and run it every time your receiver starts. Don’t use the highest id your webhook saw as the cursor: events can arrive out of order, so a missed lower id would be skipped.

import os, requests

BASE = "https://portal.zerosettle.io"
TOKEN = os.environ["ZEROSETTLE_TOKEN"]

def backfill(cursor: int) -> int:
    while True:
        r = requests.get(f"{BASE}/api/imessage/messages",
                         params={"after_id": cursor, "limit": 500},
                         headers={"Authorization": f"Bearer {TOKEN}"}, timeout=15)
        r.raise_for_status()
        page = r.json()
        for m in page["messages"]:             # both directions, in id order
            handle_once(m)                     # yours: skip ids already handled
        if page["next_after_id"] == cursor:    # nothing new
            return cursor                      # save it for the next run
        cursor = page["next_after_id"]

Signature checks and a complete receiver are in how to receive iMessages with a webhook.

How do you handle duplicates and ordering?

Deduplicate ZeroSettle webhook events on the pair of message.id and event, because a retry carries the same pair. Sort by message.id when order matters, because events for one line are delivered concurrently and can arrive out of order under retries.

A slow handler causes duplicates too: a receiver that works for more than 10 seconds before answering counts as a timeout, and ZeroSettle sends the same event again. Answer 2xx first and queue the work. Delivery is per line, so if two systems need the same messages, fan out from your own receiver. Verifying the X-ZeroSettle-Signature header before any of this is covered in ZeroSettle’s API security explainer.

Which errors mean retry and which mean stop?

Retry ZeroSettle’s busy and temporary-outage errors after a short wait, hold a new-contact send until retry_after_s has passed, and don’t resend the rest unchanged: they fail again until something changes: your input, the subscription, the token, or the recipient (a reply, or START after a STOP). Every error has one shape, {"error": {"code", "message", …}, "detail"}: branch on error.code. Rate-limited responses carry a Retry-After header.

A send that fails on the line’s side (busy, temporarily unreachable, or unable to send) keeps a stored record with status failed and reaches your webhook as message.failed, so a send that succeeds on its second try leaves a failed row and then a sent row with a new id. A STOP or awaiting_reply refusal happens before anything is sent or stored. In code:

import os, time, requests

BASE = "https://portal.zerosettle.io"
TOKEN = os.environ["ZEROSETTLE_TOKEN"]

class RetryLater(Exception):
    """Re-queue the send; retry_after_s can be hours away."""

def send(to: str, text: str, tries: int = 4) -> dict:
    for attempt in range(tries):
        r = requests.post(f"{BASE}/api/imessage/send", json={"to": to, "text": text},
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=90)
        if r.ok:
            return r.json()                    # message_sent: handed to Apple
        err = r.json()["error"]
        if err["code"] == "new_contact_limit":
            raise RetryLater(err["retry_after_s"])
        if err["code"] == "error":             # 502: iMessage check didn't finish; nothing sent
            raise RetryLater(60)
        if err["code"] not in ("line_busy", "phone_offline", "phone_timeout"):
            # 401, 402, 403, 422, 502: resending the same request fails again
            raise RuntimeError(f'{r.status_code} {err["code"]}: {err["message"]}')
        if attempt + 1 < tries:
            if err["code"] == "line_busy":
                time.sleep(int(r.headers.get("Retry-After", 2)))
            else:
                time.sleep(5 * 2 ** attempt)   # 5, 10, 20 s
    raise RetryLater(60)

How do other iMessage API providers retry webhooks?

Published webhook retry policies range from a single attempt to about three hours of retries, and ZeroSettle’s window is on the short side. Each figure below comes from that provider’s own docs.

ZeroSettle’s last retry starts about 26 seconds after a fast failure; Linq retries for 30 minutes, and LoopMessage’s retries span about three hours. On ZeroSettle, a longer outage is covered by the stored history and the after_id cursor, not by more retries. Uptime and spam flags are on the reliability and trust hub. To try it, read the API docs, compare plans, or get a number.