SMS API with iMessage: one thread for blue and green texts

Yes, one SMS and iMessage API can send both: texts to iPhones go out as iMessage on an iMessage line, texts to Android phones go out as regular SMS from your green number, and every reply lands in the same conversation thread. On Ready, an iMessage line costs $99 a month plus 6 cents a segment, and the Android side bills at the normal SMS rate if the account already had its own number (see the cost math below).

This guide is for product teams at CRMs, vertical SaaS products and other platforms who are deciding whether "blue bubbles" are worth adding for their customers. We make Ready, so the specifics below are ours. We also cover where the iMessage line is a bad fit and where a plain SMS provider is the better buy, because some of you will be better off skipping it.

How an SMS and iMessage API decides blue or green

The model is simpler than most people expect. Each sub-account has two kinds of sending identity:

• An iMessage line. An iMessage sender. Texts show up blue on iPhones, with the business's name and photo.
• A regular number (green). A 10DLC number that sends SMS and MMS to everything else.

When a sub-account sends through the iMessage line's endpoint (POST /sms/imessage, see the iMessage line API docs below), a contact on an iPhone gets iMessage from the iMessage line. A contact who is not on iMessage gets a refusal with fallback: sms and nothing is sent, so send the same text with POST /v1/messages and it goes from the account's regular number. If the account has no regular number yet, the iMessage line comes with one, so Android contacts always have a number to be texted from. That included number bills the account's texts at 6 cents a segment once the account registers or sends through GoHighLevel. If the account already had a number, Android texts bill at the regular text price.

Both sends land in one conversation per contact. POST /v1/messages always sends SMS. Your code tries the iMessage line first and resends as SMS when the answer carries fallback: sms.

What an iMessage line is not

An iMessage line is not Apple Messages for Business. Apple's service only works when the customer starts the chat, usually from a "Message us" button in Maps, Safari or an app. An iMessage line can text first, which is the behavior a CRM or vertical SaaS product needs for follow-ups, reminders and lead responses.

What the iMessage line can and can't do

The limits shape your product design, so read these before writing a spec:

• Unlimited texting with existing conversations. Anyone the business already talks to can be texted as much as needed.
• 50 new conversations per line per day. Each line can start up to 50 conversations with people it hasn't talked to before.
• Two texts until they reply. A line can send up to 2 texts to a new person before that person responds.
• Photos only after a reply. Media waits until the contact has written back.
• More new people means more lines. The "Add lines automatically" setting can add a line when the day's new conversations are used up.
• Campaigns and drip campaigns don't use the iMessage line. They send from regular numbers. The iMessage line is for conversations, not bulk sends.

The last two points carry most of the weight. An iMessage line is a one-to-one channel. If your customers' main job is sending a promo to 8,000 contacts, the iMessage line doesn't touch that traffic. If their main job is following up with 30 new leads a day and holding a conversation, it fits well.

The cap also works as a guardrail. Fifty new people a day per line rules out list blasting. Consent still applies: the iMessage line can text first, but who it texts should be people who opted in or reached out. Cold contact belongs on the phone and in the mail, not in a text thread.

One thread: replies, reactions and group chats

This is the part that makes the iMessage line worth building around. On an iMessage line, replies, reactions, typing indicators and group chats all land in the same inbox thread as SMS. A contact who started on Android and switched to an iPhone doesn't split into two conversations. A tapback on a message doesn't vanish.

For a platform, that means:

1. Your inbox UI doesn't fork. One thread per contact, with each message marked by the channel it used.
2. Reporting stays simple. Reply rates, response times and conversation counts roll up per contact, not per channel.
3. GoHighLevel stays in sync. If your customers run on GHL, Ready's native integration syncs inbound and outbound messages two ways, mapped per location. Blue and green messages show up in the same GHL conversation. Our guide on native sync versus webhook wiring explains why that matters for threading.

Reactions are free. Replies to an iMessage line bill at 6 cents a segment, the same as a send. On the green side, replies you receive bill like a sent text: $0.0075/segment plus the $0.0045 carrier fee.

Sending through the API

The SMS side uses the standard messages endpoint. Authenticate with X-API-Key and send an Idempotency-Key (any UUID) so a retried request never sends twice:

curl -X POST https://api.tryready.com/v1/messages \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Idempotency-Key: 3f6c2a1e-8d4b-4c1a-9e7f-2b5d8a0c6e91" \
  -H "Content-Type: application/json" \
  -d '{"to": "+12125550199", "body": "Your order #1042 has shipped.", "consent_attested": true}'

consent_attested is your promise that the recipient agreed to texts. Ready records that attestation per send (who sent, to how many, when) as an audit trail. That record is not a per-contact consent record. The opt-in time, wording and page URL still belong in your own store, so keep them there.

Optional fields include from (one of your numbers), media_url for MMS and from_strategy (local, even or random). Opt-outs, numbers on your Ban list and known landlines are refused up front and not charged. A text sent during the recipient's quiet hours is held if the window opens within 6 hours, and charged only when it sends; otherwise it is refused with 409 QUIET_HOURS_BLOCK and must be resent.

The iMessage line's own request shapes live in the iMessage line API docs, and the product side is in the iMessage line guide. We won't reproduce them here so this post can't drift out of date. For a full integration walkthrough covering retries, opt-out sync and error handling, see integrating an SMS API.

Webhooks

Webhooks are built in. Point one at your backend and you receive message events without polling. The payloads and event types are in the webhook docs; build against those rather than any example in a blog post. For backfills and reconciliation, GET /v1/messages pages with before_id. GET /v1/opt-outs lists the account's opted-out contacts for your UI; it leaves out a deleted contact's STOP, dialer do-not-call entries and STOPs on other sub-accounts of the same parent, so check GET /v1/opt-outs/:phone before sending from another tool.

The cost math: a worked example

Here is an example with stated assumptions, not a measured customer result.

Assumptions for one sub-account:

• 40 new conversations each weekday, 22 weekdays a month = 880 new conversations a month
• 55% of contacts on iPhone (an assumption; check your own customers' mix)
• Each conversation averages 4 outbound and 3 inbound segments = 7 segments
• One iMessage line covers it (iPhone contacts come to about 22 a day, under the 50 cap)
• The account already had its own regular number. If the iMessage line came with its green number, the account's SMS bills at 6 cents a segment once it registers, so the Android row below would cost more

Split:

• iPhone: 880 × 55% = 484 conversations × 7 = 3,388 segments
• Android: 396 conversations × 7 = 2,772 segments

The iMessage line adds roughly $235 a month for this sub-account. That figure is slightly less once you count the $0.0045 carrier fee those 3,388 iPhone segments would have carried as SMS.

Two more notes on the figures:

• Excluded charges. The SMS figures exclude the compliance surcharge. Scrubbing and landline validation each add $0.003 per segment when switched on for an account, and both are off by default.
• Local presence. Local presence for the green side has a listed price of $0.0015 for each segment of a delivered text.

How to judge the $235

The question is whether blue bubbles produce enough extra replies, booked jobs or closed deals to cover about $235 a month per sub-account. For a product whose customers close a few thousand dollars per deal, a couple of extra conversions covers it many times over. For a product whose customers send appointment reminders on a $40 service, it probably doesn't.

There are two common ways to handle the cost:

• Pass it through. Sell the iMessage line as a paid add-on and let your customers decide.
• Bundle it. Include it in a premium plan where the margin already exists.

Registration: what the iMessage line skips and what it doesn't

An iMessage line needs no 10DLC registration, so a business can start texting iPhones as soon as the line is set up. For a platform onboarding new customers, that removes a wait that otherwise sits between signup and first conversation.

The green side still follows 10DLC rules:

• Before registering. An account can send up to 500 texts a month at its normal per-text rate. After that it has to register.
• Cost of registering. Registration runs in-app. The charge at submit is the first month, $25. The ongoing monthly cost is $25 for registration and $2 per number.
• Timing. Most approvals take 2 to 7 days.
• During review. An account that bought its number before registering sends on Ready's shared registration at the same per-text rate while its own registration is in review.

If you're new to the rules, start with what 10DLC is. Sub-account registration runs through GET /v1/registration and the sub-account endpoints, which are covered in the docs.

In practice, the iMessage line lets a new sub-account hold real conversations with iPhone users on day one. The Android side has a 500-text runway before registration is required. Most customers will be registered before they hit either constraint.

When adding iMessage isn't worth it

We'd rather you skip this than buy it and churn. The iMessage line is a poor fit when:

• Your traffic is mostly campaigns. Campaigns and drip campaigns send from regular numbers, so the iMessage line does nothing for bulk sends.
• Your audience skews Android. You pay $99 a line for a minority of contacts.
• Your messages are one-way transactional. Order confirmations and shipping notices rarely need a conversation. At 6 cents versus $0.0075/segment, the iMessage line triples the per-segment cost for something the customer reads and closes.
• Your customers start hundreds of new conversations a day. At 50 new people per line per day, 500 a day means 10 lines and $990 a month in line fees before a single segment is billed.
• Lowest per-segment SMS cost is the whole requirement. If you only need green SMS and you're happy to build registration, opt-out handling and an inbox yourself, a raw CPaaS charges less per segment. Twilio runs about $0.0083/segment. Our honest Twilio comparison lays out what you get for the difference and where Twilio is the better pick.

The iMessage line earns its keep in conversation-heavy, high-value work: sales follow-up, lead response, client service, scheduling with back-and-forth. In those cases, replying from a recognizable name and photo is the reason teams turn it on.

The practical takeaway

The pieces fit together like this:

• Channels. One SMS and iMessage API gives you blue to iPhones on an iMessage line, green to Android from a 10DLC number, with your code resending as SMS when the iMessage line answers fallback: sms, and one thread for replies, reactions and group chats.
• Cost. $99 a line plus 6 cents a segment on the blue side. The SMS side bills at $0.0075/segment plus the $0.0045 carrier fee, unless the iMessage line came with the account's only green number (then 6 cents a segment once it registers).
• Limits. 50 new conversations per line per day, and bulk campaigns stay on SMS.

Before committing, run the worked example above against your own customers' numbers: new conversations per day, iPhone share and segments per conversation. If the cost per sub-account is small next to what one extra conversion is worth, add it as an option. The iMessage line guide and the quickstart are the place to start. When you want to try it, create an account. The first 20 one-to-one texts are free, and to send any text you need a card and a number ($2 a month, the first month charged when you get it).

FAQ

Can one API send both iMessage and SMS?

Yes. Send with POST /sms/imessage and, when the answer carries fallback: sms, send the same text with POST /v1/messages. iPhones get iMessage from an iMessage line, Android phones get SMS from the account's regular number, and both land in the same conversation thread.

How much does iMessage for business cost through an API?

On Ready, an iMessage line is $99 a month per line plus 6 cents a segment for each text sent. Replies to an iMessage line are also 6 cents a segment, and reactions are free. If the account already had its own number, texts to Android phones bill at the regular SMS rate of $0.0075/segment plus the $0.0045 carrier fee. If the iMessage line came with its green number, the account's texts bill at 6 cents a segment once it registers or sends through GoHighLevel.

Do I need 10DLC registration to send iMessage?

No. An iMessage line needs no 10DLC registration, so a business can text iPhones as soon as the line is set up. The regular number used for Android contacts still follows 10DLC rules: up to 500 texts a month before registering, and most approvals take 2 to 7 days.

Can a business send the first iMessage, or does the customer have to start?

An iMessage line can text first. That is the key difference from Apple Messages for Business, where the customer must start the chat. Each line can start up to 50 new conversations a day and send up to 2 texts before the person replies.

Can I send iMessage marketing campaigns to my whole list?

No. Campaigns and drip campaigns send from regular numbers, not the iMessage line. The iMessage line is built for one-to-one conversations, with a cap of 50 new people per line per day.