01
Send and receive
Start a blue-bubble conversation and receive replies through one focused API.
Put blue bubbles
inside your product.
Give your CRM, application, workflows, or AI agents a dedicated iMessage line—without building and operating the messaging infrastructure yourself.
80%higher response rates
37%more attributed revenue
Internal Miss Blue beta customer results compared with SMS outreach. Results vary.
Built for two-way messaging
An API for the whole conversation.
Send the first message, understand what happens next, and keep every reply available to both your software and your team.
02
Real-time events
Keep your product synchronized with inbound messages, delivery state, and conversation activity.
03
Rich conversations
Support attachments, reactions, replies, and the context that makes a thread useful.
04
Human handoff
Let software begin the workflow, then continue the same thread from the Message Center.
From one request to one replySimple enough to start.
Simple enough to start.
Flexible enough to become the workflow.
Use Miss Blue as the conversation layer underneath sales automation, support, scheduling, notifications, and agentic products.
CRM follow-up AI agent conversations Human escalation Delivery tracking
Send an iMessage
POST /v1/messages
Authorization: Bearer <server-held API key>
Content-Type: application/json
{
"number_id": "<granted-number-id>",
"recipient": "+12025550101",
"text": "Your requested demo is ready to schedule."
}Test a send, a reply, and a failure before connecting your workflow.
Create an account and an isolated sandbox key, find its virtual number with GET /v1/numbers, then send a simulated message through the normal API. The sandbox can produce delivery, reply, offline, rate-limit, and timeout outcomes. It does not contact a real recipient or measure Apple delivery performance.
Put the conversation where your team already works.
Trigger the right follow-up from customer data and write every reply back into the workflow.
Give your agent a channel people already answer.
Connect your own models and tools, keep context across the thread, and hand off to a person cleanly.
Production integration guide
The endpoint is the smallest part of the API.
A dependable iMessage integration needs line authorization, durable send state, inbound events, idempotency, monitoring, and a human recovery path. Miss Blue is designed around the entire conversation—not a one-off request that disappears after it returns.
Understand what an iMessage API provides
Apple’s public Messages framework is for iMessage apps and extensions that run inside the Apple Messages experience. It is not a general server-side REST API for a Linux backend, CRM, or agent to send ordinary business conversations.
A managed provider supplies the boundary your application needs: authenticated HTTP operations and conversation events on one side, operated Apple delivery infrastructure on the other.
- Server-to-server access
- Managed blue line
- Two-way conversation state
- No Apple framework in your backend
Model a line, contact, thread, and message separately
The line identifies the business sender. The contact identifies the recipient in your product. The thread keeps conversational continuity, and each message has its own provider and delivery state.
Keeping those identifiers separate prevents a CRM contact merge, number change, or retry from corrupting conversation history. Store provider IDs as integration data and retain your own stable application IDs.
- Granted line ID
- Application contact ID
- Provider thread ID
- Application and provider message IDs
Authorize every send on the server
A browser or customer-supplied line ID is not an authorization claim. Your backend should authenticate the caller and resolve the selected number through the workspace’s grant before it creates a message.
Keep API credentials in protected server configuration, rotate them through a documented process, and never expose them to client-side JavaScript, analytics, logs, or support screenshots.
- Server-held credential
- Per-line access check
- Validated destination and content
- No secrets in the browser
Treat events as durable workflow input
Inbound replies and delivery changes should reach a small HTTPS endpoint that verifies, validates, deduplicates, persists, and acknowledges. Slower CRM, agent, and notification work belongs in a bounded background worker.
Store each provider event ID before side effects. Do not assume perfect ordering, and do not let an event retry create a second task, agent run, or customer-visible response.
- Verified event source
- Unique event ID
- Fast durable acknowledgement
- Idempotent downstream work
Retry without repeating the customer message
Keep a stable logical send ID in your application and dispatch it once. Miss Blue does not currently document an Idempotency-Key header for message sends; do not assume that adding one prevents duplicates. Classify timeouts and temporary availability separately from invalid input, revoked credentials, unauthorized lines, and permanent destination failures.
When submission may have succeeded but the response was lost, reconcile the state before trying again. An ambiguous timeout is not permission to send a duplicate.
- Finite timeouts
- Bounded exponential backoff
- Permanent-error stop
- Ambiguous-outcome reconciliation
Give operations a place to recover
Logs should expose safe identifiers, error class, latency, and attempt count without message bodies. Metrics should show queue age, send outcomes, event delay, duplicate rate, and conversations waiting for a person.
The Miss Blue Message Center provides the human surface for the same platform. A teammate can continue the customer relationship when automation pauses, a tool fails, or the conversation simply needs judgment.
- Safe operational metadata
- Queue and event health
- Visible failed work
- Same-thread human handoff
Frequently asked questions
What developers ask before the first request.
Does Apple offer a public server-side iMessage REST API?+
Apple’s public Messages framework supports iMessage apps and extensions inside Messages. It is not a general REST API for a Linux service, CRM, or ordinary backend to send business iMessages. Miss Blue provides a managed server-side API boundary.
Can I use the Miss Blue API from Python, Node.js, Rust, or another language?+
The API is HTTP-based, so a server-side application can integrate from any environment with an HTTPS client. Use the exact authenticated contract and examples provided with API access.
Can the API run from Linux?+
Yes. Your Linux service calls Miss Blue over HTTPS while Miss Blue operates the Apple-specific delivery infrastructure.
How do inbound replies reach my application?+
Miss Blue provides real-time conversation events for API integrations. Verify and deduplicate events before updating CRM state or running automation.
How should retries work?+
Deduplicate dispatch in your application, set finite timeouts, and reconcile ambiguous submissions before retrying. A custom Idempotency-Key header is not a documented deduplication guarantee for Miss Blue message sends.
Can an AI agent use the API?+
Yes. Your application can connect its own model and bounded tools to message events. Keep consent, authorization, policy, and human handoff outside the model.
Does the team need to build an inbox?+
No. Miss Blue includes a Message Center for contacts and conversations. The API and team surface can participate in the same customer workflow.
Where can I see exact endpoint and event documentation?+
The public /docs reference documents endpoints, authentication, message fields, signed events, errors, and sandbox behavior. Use it for the exact contract; the example here omits account-specific values.
Explore the platform
Connect the API to the rest of the platform.
For teams
Message Center
Use a complete shared conversation platform without writing code.
For Apple contacts
FaceTime Audio calling
Call from your blue line without carrier Spam Likely labels.
For every phone
Outbound calling
Call any dialable number from your Miss Blue business line.
For follow-up
Text automation
They text a keyword or message you for the first time, and the sequence takes it from there.
Start buildingYour product is ready