Proof-of-delivery photos over iMessage for local delivery

Who uses iMessage for proof of delivery?

Proof-of-delivery texts fit businesses that drive their own orders to a door: florists, bakeries, caterers, furniture and appliance stores, and local couriers. For a gift order, the photo is often the only way the buyer learns the flowers or the cake arrived, because the buyer is not at the address.

The photo replaces three things: “was it delivered?” calls on a busy afternoon; MMS photos, which above 600 KB “may be compressed and distorted due to carrier constraints”, per Klaviyo's MMS image guidance; and drivers texting from personal numbers, where buyers' replies never reach dispatch. Shipped parcels belong to “where is my order?” support, a photo of who is coming to the door to technician on-the-way texts, and photos sent during a service to pet care updates; more workflows are in 50 ways businesses use iMessage.

How iMessage proof-of-delivery texts work, step by step

Your delivery software calls ZeroSettle's send endpoint at the drop-off (and, if you like, when the driver heads out), and ZeroSettle carries the buyer's reply back. ZeroSettle does not watch your driver app.

1. At checkout, a box reads “Text me delivery updates and a photo”. Store the buyer's number, the ticked box and the time with the order. Then get a reply before delivery day: send an order confirmation that asks for one (“Reply with any delivery notes”), or let the buyer text first from an sms: link on the order page. ZeroSettle refuses photos to anyone who has never replied with 403 attachment_before_reply.
2. Optionally, when the driver heads to the stop, your backend sends an “on the way, about 15 minutes out” text with POST https://portal.zerosettle.io/api/imessage/send. The text names the shop, and ZeroSettle shares your brand name and photo with it (see what customers see).
3. When the driver marks the drop-off, the app uploads the photo, and your backend calls the same endpoint with image_b64 and the caption as text. The call returns once the line hands the bubble to Apple, normally in 2–5 seconds (at most about 105 for a photo). If the buyer never replied, send the caption as a text and email the photo instead.
4. The response carries the stored message id, and the same record reaches your webhook as message.sent. Store the id with the order as your record that the photo left the line.
5. A reply such as “leave it at the side door” reaches your webhook as message.received about 1–2 seconds after the line receives it, and shows live in the ZeroSettle console for the dispatcher.

What happens to the driver's photo

ZeroSettle sends a delivery photo untouched only when it is a JPEG, PNG or GIF within 2,048 px and 5 MB, and that decides whether the photo's location data reaches the buyer.

Source: ZeroSettle iMessage API docs, “Attachments”.

The first row is the one to watch. When Location Services is on for the Camera app, the coordinates are “embedded into each photo”, per Apple, so a pass-through JPEG of a gift drop-off carries the recipient's location to anyone the buyer forwards it to. Resizing to 2,048 px and re-saving without EXIF, as the code below does, removes it and keeps the photo sharp. The full attachment rules are in what an iMessage API can send.

Example conversation: a delivery photo for a gift order

A buyer orders flowers for a friend and ticks the box at checkout. The buyer replies to the on-the-way text, so the photo can follow, and gets two texts and a tapback from the shop's number; the friend gets nothing.

Setup: from a drop-off event to a photo send

The send, a resize that keeps the photo within ZeroSettle's pass-through size, and a signed webhook receiver fit in one file, following the send docs and the webhook steps. Your backend calls delivered() when the driver app uploads the photo, with the buyer's number, the photo's bytes and the caption.

# delivery_photos.py: run with  uvicorn delivery_photos:app --port 8100
import base64, hashlib, hmac, io, json, os, time
import requests
from fastapi import BackgroundTasks, FastAPI, Request, Response
from PIL import Image, ImageOps, UnidentifiedImageError   # pip install pillow

BASE = "https://portal.zerosettle.io"
AUTH = {"Authorization": f"Bearer {os.environ['ZEROSETTLE_TOKEN']}"}
SECRET = os.environ["ZEROSETTLE_WEBHOOK_SECRET"]
app = FastAPI()
seen: set[tuple[int, str]] = set()               # use your database in production

def send(payload: dict) -> dict:                 # the on-the-way text is send({"to": ..., "text": ...})
    for _ in range(5):
        r = requests.post(f"{BASE}/api/imessage/send", headers=AUTH, json=payload, timeout=120)
        body = r.json()
        if r.ok or body["error"]["code"] != "line_busy":
            return body
        time.sleep(2)                            # one send at a time per line
    return body

def delivered(buyer: str, photo: bytes, caption: str) -> dict:   # driver marks the drop-off
    try:
        img = ImageOps.exif_transpose(Image.open(io.BytesIO(photo)))
    except UnidentifiedImageError:               # HEIC: ZeroSettle re-encodes it, dropping GPS
        return send({"to": buyer, "image_b64": base64.b64encode(photo).decode(), "text": caption})
    img.thumbnail((2048, 2048))                  # within 2,048 px: sent exactly as is
    out = io.BytesIO()
    img.convert("RGB").save(out, "JPEG", quality=85)             # saved without EXIF: no GPS
    return send({"to": buyer, "image_b64": base64.b64encode(out.getvalue()).decode(),
                 "image_format": "jpg", "text": caption})

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)

def note_for_driver(m: dict) -> None: ...        # your dispatch app: add m["text"] to the open order

@app.post("/webhook")
async def webhook(req: Request, tasks: BackgroundTasks):
    raw = await req.body()
    if not verify(SECRET, req.headers.get("X-ZeroSettle-Signature", ""), raw):
        return Response(status_code=401)
    ev = json.loads(raw)
    m = ev.get("message")
    if ev["event"] == "message.received" and m and (m["id"], ev["event"]) not in seen:
        seen.add((m["id"], ev["event"]))         # retries carry the same id and event
        tasks.add_task(note_for_driver, m)       # "leave it at the side door"
    return {"ok": True}

Register the receiver with PUT /api/imessage/webhook and keep the secret, which is shown once. When several drivers finish together, sends queue on the line, and one that waits about 12 seconds returns 429 line_busy, which send() retries after 2 seconds. Requeue a new_contact_limit text after error.retry_after_s, never retry recipient_opted_out, and on 403 attachment_before_reply (the buyer never replied) send the caption as a text and email the photo.

Limits and consent for proof-of-delivery texts

Each buyer counts once as a new contact, on the first text the line delivers to them (a photo can't be the first message); the photo after an on-the-way text belongs to an ongoing conversation and does not count again. The limits apply to the console as well as the API.

Source: ZeroSettle iMessage API docs, “Errors, limits, and compliance”. Messages sent within 5 minutes of the first count as one.

The limit math for Valentine's Day

Take a florist with 80 deliveries on February 14, all to buyers the shop's number has never texted.

• First text on the day, one Pro number: 5 buyers hear from you; the other 75 sends return 429 new_contact_limit until the 3 AM Eastern reset, after the holiday.
• Growth with three numbers: 150 a day fit, but only 9 per 15 minutes (3 per number), so if 15 buyers get their first text in the same quarter hour, 6 of those sends wait.
• Text at checkout instead: the buyer then counts on the order day. If no single order day brings more than 5 new buyers, one Pro number covers them all, and the February 14 texts go to ongoing conversations.
• On either plan, that makes three unanswered messages: confirmation, on-the-way text and photo, so the photo returns 403 awaiting_reply unless the buyer replied or tapbacked in between, and a buyer who has never replied can't receive the photo at all. Ask for a reply in the confirmation (“Reply with any delivery notes”).

When ZeroSettle is not a fit for proof of delivery

ZeroSettle is the wrong tool for delivery confirmations in these cases:

• You would text gift recipients who didn't opt in. ZeroSettle suspends lines used for unsolicited messaging.
• Peak days bring hundreds of first-time buyers to one Pro number. Pro allows 5 new contacts a day per number; move first texts to the order day or use Growth's several numbers.
• Buyers won't reply before delivery. ZeroSettle sends photos only to contacts who have replied, so a buyer who never answers gets the caption as text, and the photo by email.
• Many buyers use Android. iMessage reaches Apple users only; Apple's own Messages app sends to non-Apple phones as SMS, MMS or RCS, as Apple explains, and ZeroSettle has no such fallback. Email those buyers the photo. You can check whether a number is on iMessage first, and the check sends nothing.
• You need signature capture or video proof. ZeroSettle sends photos and voice messages, not video or files; keep signatures in your delivery app.
• You need proof the buyer saw the photo. The API reports message.sent and message.failed, not delivered or read status.

How much do iMessage proof-of-delivery texts cost?

Proof-of-delivery texts cost only the plan price: ZeroSettle charges no per-message fees, and messages are unlimited (counted).

Both plans carry a 30-day money-back guarantee on the subscription. AI credits are used only by the hosted AI agent, so this flow uses none. See ZeroSettle pricing, the iMessage API docs, or get a number.