MsgBubbles API

MsgBubbles is a unified messaging API: send and receive iMessage, SMS, and WhatsApp from a real business phone number through one REST endpoint and one webhook URL. No Apple hardware, carrier accounts, or phone numbers to operate on your side.

Base URL

All endpoints live under /v1:

https://api.msgbubbles.com/v1

Requests and responses are JSON (attachments upload via multipart/form-data). Every request is authenticated with your API key — see Authentication.

Response format

Every successful response wraps its payload in a data envelope and carries a request_id (also returned as the X-Request-Id header) — quote it when reporting an issue:

{ "data": { /* the resource, or an array for lists */ }, "request_id": "req_…" }

Lists add a sibling has_more for cursor pagination, and errors share one shape too — see Errors & limits.

Quickstart

1. Get an API key

API keys are issued when your account is set up, in the form sk_live_… (or sk_test_… for test mode). The key is shown exactly once — store it in a secret manager.

2. Find your sendable numbers

Each account has one or more provisioned numbers. List them, and the channels each one serves, with:

curl https://api.msgbubbles.com/v1/numbers \
  -H "Authorization: Bearer sk_live_…"

{
  "data": [
    {
      "handle": "+18005551111",
      "channels": ["imessage", "sms"],
      "label": "support line",
      "status": "online"
    }
  ]
}

3. Send a message

curl -X POST https://api.msgbubbles.com/v1/messages \
  -H "Authorization: Bearer sk_live_…" \
  -H "content-type: application/json" \
  -d '{
    "to": "+15555550123",
    "from_handle": "+18005551111",
    "text": "hello from MsgBubbles"
  }'

The API answers 202 with the message in status queued; delivery happens asynchronously. iMessage vs. SMS is decided per recipient automatically — blue or green bubbles, you send the same request. See Messages for the full request shape, statuses, and follow-up actions like editing and reactions.

4. Receive replies and receipts

Register a webhook and MsgBubbles POSTs you message.received, message.delivered, message.read, and more — each delivery signed so you can verify it came from us. See Webhooks.

What you can build on

• Messages — send text, effects, replies, tapback and emoji reactions; edit and unsend on iMessage.
• Attachments — images, video, files, and native voice-note bubbles.
• Conversations — threads are tracked for you; create and manage iMessage group chats, mark threads read, show typing indicators.
• Webhooks — signed event deliveries with automatic retries.