What happens if your iMessage number is flagged as spam?

How do you know a number has been flagged?

A flagged ZeroSettle number fails every send, to every recipient, at once; a problem with one contact fails only that contact. ZeroSettle's docs list no error code or webhook event specific to a flag, so the signal is a pattern: message.failed events ("A send was recorded but not delivered") spread across many different people, with no message.sent in between.

ZeroSettle posts message.sent for sends "from your code, the console, or MCP", so a webhook receiver sees every one of them. Call the watcher below for every event your receiver has verified (X-ZeroSettle-Signature) and deduplicated (message.id plus event), before the docs' sample receiver returns early on anything but message.received (ZeroSettle webhook docs). It alerts when five or more people have failed sends within 30 minutes and nothing has gone out:

import time
from collections import deque

WINDOW_S, MIN_RECIPIENTS = 30 * 60, 5   # tune to your volume
recent: dict[str, deque] = {}
last_alert: dict[str, float] = {}

def watch(ev: dict, alert) -> None:
    if ev.get("event") not in ("message.sent", "message.failed"):
        return
    m, now = ev["message"], time.time()
    key = m.get("line_id", "only")       # one-number accounts carry no line_id
    q = recent.setdefault(key, deque())
    q.append((now, ev["event"], m["handle"]))
    while now - q[0][0] > WINDOW_S:
        q.popleft()
    failed = {h for _, e, h in q if e == "message.failed"}
    if (len(failed) >= MIN_RECIPIENTS and all(e == "message.failed" for _, e, _ in q)
            and now - last_alert.get(key, 0) > WINDOW_S):
        last_alert[key] = now
        alert(key, failed)               # page a person

STOP and unanswered-message refusals store nothing, so they never reach this counter. A busy or briefly unreachable line does: the docs say a failed send "keeps its record", so a send that fails with 429 line_busy or 503 also posts message.failed. If your own sends are getting those codes, retry with backoff first. If failures keep spreading without them, queue outgoing messages rather than retrying them, and contact ZeroSettle.

What does ZeroSettle do when a number is flagged?

ZeroSettle replaces a flagged number right away at no extra charge, and your integration keeps running unchanged. ZeroSettle is an iMessage API: a real phone number on real iMessage, running on Apple hardware we operate for you, that your code texts customers from and hears back on through a bearer token and signed webhooks (what ZeroSettle is). Its homepage FAQ says:

If it does happen, we replace the number right away at no extra charge. Your API token, webhook, and code stay exactly as they are, so your integration keeps running without changes.

zerosettle.io, FAQ "What if a number does get marked as spam?"

For accounts with several numbers, the docs add that the line "keeps its line_id, conversations, message ids, name and photo, and STOPs, and only its number (line) changes." A one-number account never sees a line_id; the homepage wording above is its published promise.

What changes for your customers?

Your customers see texts from a new number, and their thread with the old number does not carry over. To their iPhone the replacement is an unknown sender, even if they saved the old number, so the first text from it has to work like a first message.

• Links wait for a reply. ZeroSettle's docs: "Until the recipient replies to your number or saves it as a contact, a link in your text shows as plain text they can't tap" (why first-message links aren't tappable).
• The first text can be screened out. The docs add that Screen Unknown Senders (iOS 26) moves texts from unknown senders into a separate list without a notification, "so a cold first text may never be seen."
• Reporting is one tap away. Apple's iPhone User Guide says a Report Spam link "appears at the bottom of any message from any unknown sender", and "You can't report a message after you've replied to it."
• Say who you are and that the number changed, then ask something answerable in a word.
• Don't announce it to everyone at once. A burst of "new number" texts to people not expecting one is the unanswered messaging that gets numbers flagged. Mention the change in the next message each customer was due to get anyway.

What should your code do?

Your code needs no change for the replacement itself, because the token and webhook stay the same; what breaks is anything that stored, sent from or printed the old number. The docs' rule is "Store line_id; show line."

1. Key per-line records (routing, CRM fields, reports) on line_id, which messages, conversations, opt-outs and webhook payloads carry on a multi-number account. A one-number account has none; key on the account.
2. When you choose the sending line, pass line_id, not line: the docs note that line "changes if the line's number does", and a number that is no longer one of your lines is refused with 404 unknown_line. Never compare message.line with a hardcoded number.
3. Read the number you display from GET /api/imessage/line: handle, or each entry's number in lines.
4. Regenerate whatever prints it: sms: links, QR codes, email footers, app screens. An sms: link also lets customers text the new number first, which makes it a known sender.

export BASE=https://portal.zerosettle.io
curl -s -H "Authorization: Bearer $ZEROSETTLE_TOKEN" $BASE/api/imessage/line \
  | jq '{number: .handle, lines: [.lines[]? | {id, number}]}'

A CRM integration should store line_id on each contact rather than the number, as in logging iMessages in HubSpot or Salesforce.

How do other providers handle flagged numbers?

Published policies differ: ZeroSettle replaces the number, Linq moves recipients to another line in your pool, and myCRMSIM's guide sends you to Apple Support. Each entry comes from the vendor's own page.

Self-hosted setups on your own Mac and account have no vendor in between, so recovery is likewise up to you and Apple (self-hosting vs a managed API). ZeroSettle is the wrong choice if you must keep one specific number: a replacement is a different number, and there is no porting. Project Blue's messaging page, by contrast, offers to port your existing number (as of October 2026).

What if the line was used for unsolicited messaging?

ZeroSettle suspends it. The docs: "ZeroSettle suspends lines used for unsolicited messaging. If you are unsure whether you have consent, you don't." The homepage puts it as "Unsolicited messaging gets a line suspended", and the docs describe no replacement for a suspended line. The iMessage API Terms also say ZeroSettle "is not responsible for any action Apple or any carrier takes" on a line, number or message, "including restriction, suspension, or non-delivery".

How do you keep a number from being flagged?

Message people who asked to hear from you, at the pace ZeroSettle's limits enforce. The docs: "Repeated messages to people who never answer are the fastest way to get a number flagged by Apple."

• Let customers text first with an sms: link or QR code; anyone who texted the line first is never limited.
• Stop after two unanswered messages. Every plan enforces it with 403 awaiting_reply.
• Know the new-contact limits: per number, Pro allows 5 a day, Growth 50 a day and 3 per 15 minutes. "This is what keeps the number out of Apple's spam filters," the docs say, and they call the limits "a floor, not a licence".

The full guide is keeping a business iMessage number out of spam filters; see also how reliable ZeroSettle is, how STOP works and the reliability and trust hub. To build, read the limits and error reference or get a number.