Core concepts

Phone numbers

We accept several phone-number formats and normalize internally. Use E.164 in your code for safety — every other format gets re-formatted to it on our side.

E.164 (recommended)

Always pass + followed by the country code and number, no spaces or dashes:

"to": "+15551234567"   // US
"to": "+447700900123"  // UK
"to": "+33612345678"   // France

Formats we also accept

5551234567 — bare 10-digit → assumed US, normalized to +15551234567
15551234567 — 11-digit starting with 1 → US, normalized to +15551234567
(555) 123-4567, 555-123-4567, 555.123.4567 — punctuation stripped
+1 (555) 123-4567 — spaces/parens/dashes stripped

Country detection isn't magic

A bare 10-digit number is assumed US. If your customer base is international, always pass E.164 so we don't guess the wrong country.

Verify a number is iMessage-capable

Before sending to an unknown phone, check whether the recipient is on iMessage. Saves you a failed send + a wasted slot in your warmup budget.

curl -X POST 'https://api.bluereplies.com/v1/lookup' \
  -H "x-api-key: $BLUEREPLIES_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "phoneNumber": "+15551234567" }'

{
  "phoneNumber": "+15551234567",
  "iMessage": true,
  "carrier": "T-Mobile",
  "countryCode": "US",
  "lineType": "mobile",
  "checkedAt": "2026-05-25T17:23:14.221Z"
}

See Number lookup for bulk + caching options.