Authentication
Every API request carries your secret key in the Authorization header:
curl https://api.msgbubbles.com/v1/messages \
-H "Authorization: Bearer sk_live_…"API keys
- Keys look like
sk_live_…(production) orsk_test_…(test mode) and are issued during onboarding. - The plaintext key is shown exactly once. We store only a hash, so a lost key cannot be recovered — it can only be replaced.
- Keep keys server-side. Never embed them in mobile apps or browser code; anyone holding the key can send messages as your numbers.
Auth errors
| Status | Meaning |
|---|---|
401 unauthorized | The key is missing, malformed, unknown, or revoked. |
403 forbidden | The key is valid but the account is not active. |
Account scoping
A valid key is necessary but not sufficient. Everything you can reach — messages, conversations, attachments, webhooks — is scoped to your account, and the from_handle on a send must be a number assigned or granted to you. Requests against another account’s resources return 404, never someone else’s data.
Your numbers
GET/v1/numbers
Lists the numbers your account can send from and what each can do — useful for rendering a from-number picker:
{
"data": [
{
"handle": "+18005551111",
"channels": ["imessage", "sms", "whatsapp"],
"label": null,
"status": "online",
"allocation": "dedicated"
}
],
"request_id": "req_…"
}label is reserved for a display name and is currently always null — name your numbers in your own UI.
Dedicated and pooled numbers
Each organization has its own API key, conversations, attachments, and webhooks. A dedicated fleet line belongs to one organization. A pooled fleet line can be granted to several organizations. The numbers response includes allocation: dedicated or pooled. WhatsApp sessions remain specific to your account; WhatsApp pooling is not supported.
A successful send from a pooled line permanently reserves that line and recipient handle for your organization. Events for that conversation go only to your organization. If another organization already reserved the same pair, POST /v1/messages returns 409 pooled_recipient_conflict without queuing a message. Select another granted line from GET /v1/numbers and retry. Line selection is explicit; it is not automatic.
Pooled lines are send-only. Your messages go out, and you still get delivery receipts, read receipts, and failure events for them. Nothing a contact sends on a pooled line reaches you: no replies, attachments, reactions, or typing indicators. A contact can’t start a conversation on a pooled line, and group messaging isn’t supported there.
The one reply a pooled line acts on is an opt-out. When a contact you’ve messaged from a pooled line replies STOP, msgbubbles stops your messages to them, and START opts them back in.
If you need to receive replies, let contacts message you first, or use group messaging, use a dedicated line. The SMS sending limitations described in Messages apply on pooled lines too.
Revoking a shared-line grant stops new sends and is rechecked at queued dispatch, although a provider request already in flight may finish. The reservation and history remain yours, and a later STOP or START from that contact still applies to your organization. Reservations do not expire or transfer to another organization. Removing a grant does not revoke your API key or disable webhooks. Onboarding and grants are managed by the service operator.
Organizations share the physical line’s sending capacity and per-line pacing. Each organization also retains its per-key HTTP rate limit.
allocation is dedicatedfor a number that’s yours alone, or pooled for a shared number that other customers also send from. On a shared number, msgbubbles enforces opt-outs for you.
Switching from a pooled line to a dedicated one
Pooled lines are send-only, so to receive replies you need a dedicated line. The service operator assigns it, the same way it manages grants. Once it’s yours, it appears in GET /v1/numbers with "allocation": "dedicated". Then:
- Send from the new number. Line selection is explicit, so your sends stay on the pooled line until you change
from_handle. If you keep it in config, such asMSGBUBBLES_PHONE_NUMBER(see Configure your app), set it to the new number and redeploy. - Keep your API key and webhooks.Both belong to your organization, not to a line, so the key, webhook URL, and signing secret don’t change.
- Subscribe to inbound events. On a dedicated line, replies, attachments, reactions, and typing indicators reach you, contacts can text you first, and you can use group messaging. An endpoint registered without an
eventslist already receives everything. If you chose events while on the pooled line, addmessage.receivedand anything else you now want withPATCH /v1/webhooks/:id. - Handle opt-outs yourself. msgbubbles enforces opt-outs only on shared numbers. On your dedicated number, a
STOPreply arrives as an ordinarymessage.received, and opt-outs recorded on your shared numbers don’t block sends from it. Carry your opt-out list over using theconversation.opted_outevents you’ve already received. - Expect new threads. A conversation is a thread between one of your numbers and a contact, so your first send from the new number starts a new conversation. Your pooled-line conversations and their history stay in your account.
Monthly message allowances
Your administrator can set a monthly allowance such as 1,000 message operations. It is shared across all your organization’s keys, numbers, and channels. The window is a UTC calendar month, resetting at 00:00 UTC on the first day of the next month. Accounts default to unlimited.
GET/v1/usage
Use your own bearer key to read your allowance and current usage:
{
"data": {
"monthly_limit": 1000,
"used": 42,
"remaining": 958,
"period_start": "2026-10-01T00:00:00.000Z",
"resets_at": "2026-11-01T00:00:00.000Z"
},
"request_id": "req_example"
}Each accepted POST /v1/messages counts once, including sends that later fail delivery. Idempotent replays, automatic retries, and retrying an existing failed message do not count again. Inbound messages, reads, edits, reactions, typing and webhook deliveries do not count. Attachment count, text length and channel do not change the one-slot cost.
Group creation reserves one slot before attempting its opening message. That slot remains consumed if the sending operation times out or returns an error, because delivery may already have happened. A replay resolved before a new send attempt does not count again.
Exhaustion returns 429 monthly_quota_exceeded with Retry-After seconds until the reset. A quota-rejected send is not queued. Read access and inbound replies continue at the cap. Your administrator can raise the allowance or remove it; changing a limit or issuing another key does not clear usage. A zero limit blocks new sends; previously accepted messages and retries can still finish.
Unlimited accounts have monthly_limit: null and remaining: null; their future usage is still recorded. Counters start when the quota feature is deployed; earlier history is not backfilled. This allowance is independent of HTTP request limits and per-number pacing.
Rate limits and the error envelope are described in Errors & limits.