Sending rules

Blujay enforces a small set of rules on every message your integration sends. They exist because Apple and the carriers judge a phone number by how people respond to it, and a number that gets filtered stops delivering for everyone it messages. The rules are the same on every plan. The errors are 400 or 403, never retryable, and nothing is sent when you get one. This page is the contract. Sending best practices is the advice that keeps you well inside it.

​

Before the contact replies

Until a contact has replied to your phone number, Blujay rejects three kinds of send: Blujay treats anything that looks like a domain name as a link, including example.com without https:// and the domain in an email address such as help@example.com. Keep those out too. The rules lift for that contact on that number as soon as they reply. They apply per number: a contact who has replied to your Support number has not replied to your Sales number.

​

Texts in a row without a response

Before and after a first reply, Blujay sends at most 6 texts in a row to a contact without a response from them. The 7th returns 400 PRE_REPLY_LIMIT_REACHED. The count covers every message the person gets from your workspace, from any of your numbers, the Blujay apps, workflows and the API together. A photo or file with no text counts as one text; a caption and its attachment count as one. The count starts again each time they respond, on any of your numbers. To send one more text after the limit, for something the person needs, set pre_reply_override: true at the top level of the request body. It allows a 7th text and nothing after it until the contact responds. It is not a way around the rule. The override works only when exactly 6 texts are unanswered; a contact with a longer unanswered history (for example 20 texts sent before you turned on the API) is refused with or without it, until they respond. Every one of these errors carries details[0] with rule (link, attachment, length or limit), limit (300 characters for length, 6 texts for limit, null for the others) and unanswered_count (for limit).

​

What counts as a response

• A text from the contact, in the direct chat or in a group chat your number is in.
• A reaction (tapback) from the contact.
• Calls never count. The limits protect the iMessage number, which never sees a call.

A response from the contact lifts the content rules for that number and restarts the 6-text count.

​

Group chats

The same rules apply to a group chat, counted for the group:

• Until anyone in the group replies, links, attachments and texts over 300 characters are rejected.
• At most 6 texts go to the group in a row without a response from anyone in it.
• The rules apply to every POST /v1/chats that starts or reuses a group, even when some members already have direct chats with you.

​

Who you can message

See Plans for what each plan can do.

​

Limits on each number

These are 429 errors with a Retry-After header, and they are retryable. Nothing is sent when you get one. Read the live values from limits and queue on GET /v1/phone-numbers before a batch. Those fields are the source of truth; the numbers above are today’s typical values, and sending limits can change at any time.

​

Handle these errors

• Don’t retry a 400 or 403 from this page. Wait for the contact to reply, then send the link, file or longer text as a follow-up with a sentence that says what it is.
• On a 429, wait for Retry-After, then retry with the same Idempotency-Key, or send from another number.
• To know before you send, read the contact’s opted_out and messaging_allowed, and the number’s outbound_policy.inbound_first, send_status, limits and queue. There is no field that reports a contact’s pre-reply state today; the first text you send tells you.

​

Next steps