Sending best practices

Apple and the carriers decide whether your messages arrive based on how people respond to them. Messages that get replies keep a number healthy. Messages that go unanswered, or get reported as junk, get a number filtered or blocked, for everyone it messages. These rules apply to every message your integration sends.

​

Every new contact

​

Dos and don’ts

​

Write like a person

Each message should read as if one person wrote it to one other person.

• Say who you are and why you’re writing in the first line.
• Ask one question that’s easy to answer from a lock screen.
• Keep it to a line or two. Send a second message instead of a paragraph.
• Vary the wording between recipients. Identical messages sent to many people read as automated, to people and to spam filters.

​

The rules Blujay enforces

Blujay rejects links, attachments, contact cards and texts over 300 characters until a contact replies to your number, and sends at most 6 texts in a row to anyone who hasn’t responded. These are hard rules with their own error codes. They are listed once, with the exact errors, on Sending rules. Everything on this page is advice for staying well inside them.

​

Pace new conversations

A Dedicated number can message up to 50 people it has never texted before per day. A new or recently reassigned number may start lower and reaches the full limit over about its first month. People who messaged you first never count against it, and you can always keep messaging people you already talk to. The live values are in limits on GET /v1/phone-numbers.

• Read GET /v1/phone-numbers before a batch, and stop when limits.new_contacts.remaining_today or queue.remaining reaches zero.
• Spread sends over the day instead of sending them all at once.
• If you have several numbers, spread new conversations across them.
• Keep each person on the same number. Once a number has texted someone, keep using it for that person: switching numbers mid-conversation looks like spam to carriers.
• On RATE_LIMIT_EXCEEDED, wait for Retry-After or schedule the send for the next day. Don’t switch numbers to get around a limit for the same recipient.

​

Follow up sparingly

• At most two follow-ups a week to any one person, and stop after two follow-ups with no reply. That’s well under Blujay’s limit of 6 in a row, which is a backstop, not a target.
• Count everything a person gets from you, including messages from automations and from teammates on other numbers. Blujay counts them all toward the limit.
• To restart a quiet conversation, ask something short: “Still worth keeping this open?”

​

Respect opt-outs

When someone asks you to stop, opt them out right away. Blujay then refuses API sends to them with RECIPIENT_SUPPRESSED, so a bug in your code can’t message them again.

​

Aim for replies

A number stays healthy when the people it texts write back. Aim for at least 3 in 10 of the people you start a conversation with to reply. Below that, the number’s health score drops. Short, personal, specific messages get the most replies.

​

Use typing indicators

Before you send a reply in an iMessage chat, start a typing indicator with POST /v1/chats/{chat_id}/typing. The other person sees the typing bubble, so an automated answer feels attended. It’s best effort and shows only in iMessage chats; SMS and RCS chats accept the request and show nothing.

​

Watch your numbers

• Check send_status.allowed and health_status on GET /v1/phone-numbers regularly. A degraded or critical number needs fewer new conversations and more replies.
• Reply quickly when someone answers. Conversations with real back-and-forth are what keep a number healthy.
• Subscribe to message.failed and watch for a rise in failures.

​

Check your integration with AI

When your integration works, have your AI coding assistant review it against these docs. The prompt is on Build with AI.

​

Next steps