curl -X POST https://api.ibubbl.com/v1/messages/8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b/unsend \
-H "Authorization: Bearer $IBUBBL_API_KEY"
const messageId = "8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b";
const res = await fetch(
`https://api.ibubbl.com/v1/messages/${encodeURIComponent(messageId)}/unsend`,
{
method: "POST",
headers: { Authorization: `Bearer ${process.env.IBUBBL_API_KEY}` },
signal: AbortSignal.timeout(10_000),
},
);
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.detail?.error}`);
// 202: the Undo Send is on its way; 200: already unsent or being unsent.
console.log(res.status, data.unsend_status);
import os
import urllib.parse
import requests
API_KEY = os.environ["IBUBBL_API_KEY"]
message_id = "8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b"
res = requests.post(
f"https://api.ibubbl.com/v1/messages/{urllib.parse.quote(message_id, safe='')}/unsend",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['detail']['error']}")
# 202: the Undo Send is on its way; 200: already unsent or being unsent.
print(res.status_code, data["unsend_status"])
{
"id": "8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b",
"direction": "outbound",
"created_at": "2026-11-05T15:04:10.112730Z",
"status": "read",
"to": "+14155551234",
"body": "",
"contact_id": "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f",
"conversation_id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
"conversation_kind": "one_to_one",
"chat_guid": null,
"channel": "imessage",
"sent_at": "2026-11-05T15:04:12.381Z",
"held_until": null,
"held_reason": null,
"effect": null,
"reply_to_message_id": null,
"attachments": [],
"edited_at": null,
"edit_count": 0,
"edit_status": null,
"unsend_status": "pending",
"unsent_at": null
}
{
"detail": {
"error": "unsend_window_expired",
"message": "This message can no longer be unsent."
}
}
Unsend a message
Take back a message you sent over iMessage, within 110 seconds of sent_at (iMessage allows two minutes).
The Undo Send is accepted with unsend_status: "pending", and body is empty at once. When it reaches the recipient, message.unsent fires with direction: "outbound". If it doesn’t, message.unsend_failed fires and body comes back.
On iOS 16, iPadOS 16.1, macOS 13 Ventura, visionOS 1 and later the message disappears and both sides see a note that it was unsent. On earlier versions the original stays in the conversation: never rely on Undo Send to retract sensitive information.
A message that went out with a link preview is two bubbles; both are unsent. A message with files (text and files, or several files) can’t be unsent through the API (422 multi_part).
Repeating the request while the Undo Send is pending or done answers 200 and changes nothing; after message.unsend_failed it tries again, if it’s still within the window.
Counts toward the conversation-actions rate limit (300 a minute per account).
curl -X POST https://api.ibubbl.com/v1/messages/8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b/unsend \
-H "Authorization: Bearer $IBUBBL_API_KEY"
const messageId = "8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b";
const res = await fetch(
`https://api.ibubbl.com/v1/messages/${encodeURIComponent(messageId)}/unsend`,
{
method: "POST",
headers: { Authorization: `Bearer ${process.env.IBUBBL_API_KEY}` },
signal: AbortSignal.timeout(10_000),
},
);
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.detail?.error}`);
// 202: the Undo Send is on its way; 200: already unsent or being unsent.
console.log(res.status, data.unsend_status);
import os
import urllib.parse
import requests
API_KEY = os.environ["IBUBBL_API_KEY"]
message_id = "8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b"
res = requests.post(
f"https://api.ibubbl.com/v1/messages/{urllib.parse.quote(message_id, safe='')}/unsend",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['detail']['error']}")
# 202: the Undo Send is on its way; 200: already unsent or being unsent.
print(res.status_code, data["unsend_status"])
{
"id": "8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b",
"direction": "outbound",
"created_at": "2026-11-05T15:04:10.112730Z",
"status": "read",
"to": "+14155551234",
"body": "",
"contact_id": "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f",
"conversation_id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
"conversation_kind": "one_to_one",
"chat_guid": null,
"channel": "imessage",
"sent_at": "2026-11-05T15:04:12.381Z",
"held_until": null,
"held_reason": null,
"effect": null,
"reply_to_message_id": null,
"attachments": [],
"edited_at": null,
"edit_count": 0,
"edit_status": null,
"unsend_status": "pending",
"unsent_at": null
}
{
"detail": {
"error": "unsend_window_expired",
"message": "This message can no longer be unsent."
}
}
Unsend a message
Method:POST | Endpoint: /v1/messages/{message_id}/unsend
Description: Take back a message you sent over iMessage, the way Undo Send works on an iPhone: within 110 seconds of sending. See Edit, Undo Send and Cancel.
Authentication: API key in the Authorization header: Authorization: Bearer ib_pk_<64 hex>. Create keys in the dashboard under Settings → API access.
Rate limit: 300 conversation actions per 60 seconds per account (edits, unsends, cancels, tapbacks, mark read and typing together, across all your API keys). Over that, you get 429 rate_limited with a Retry-After header; see Rate limits.
Request Body
None. The path parametermessage_id is the id of a message you sent: from Send a message, or from List messages, where messages sent from the dashboard appear too.
How it behaves
- It’s accepted first, applied second. The answer is
202withunsend_status: "pending", andbodyis already empty. A few seconds later the message is gone from the recipient’s conversation:message.unsentfires withdirection: "outbound"andscope: "message", andunsend_statusbecomesunsent. - If it doesn’t land, the text comes back.
message.unsend_failedfires,unsend_statusbecomesfailed, andbodyreturns: the recipient still has the message. Calling again tries once more, if the 110 seconds aren’t up. - It’s safe to call twice. While the Undo Send is pending, or once it’s done, calling again answers
200with the message and changes nothing. - 110 seconds. Measured from
sent_at. iMessage allows 2 minutes; iBubbl stops 10 seconds early so the Undo Send never arrives too late. After that,422 unsend_window_expired. - Not while an edit is on its way.
409 edit_in_flight: wait formessage.edited(a few seconds), then unsend. - iMessage only. A message that went out by SMS (
channel: "sms", RCS included) can’t be unsent:422 sms_not_supported. One that hasn’t gone out yet gets422 not_sent_yet: cancel it instead. - One bubble at a time. A text message, or a message that is one file and nothing else, is unsent whole. A message with files and text, or several files, shows as several bubbles and gets
422 multi_part: unsending part of a message is available in the dashboard only, for now. - Messages with a link preview. A message typed in the dashboard with a link goes out as two bubbles, the text and a preview card. Unsending it takes back both. Messages sent through the API never have a preview card, so they are one bubble.
- Opted-out contacts don’t block it. An Undo Send only removes content, so it works whatever the contact’s opt-out or block status. Groups work too.
curl -X POST https://api.ibubbl.com/v1/messages/8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b/unsend \
-H "Authorization: Bearer $IBUBBL_API_KEY"
const messageId = "8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b";
const res = await fetch(
`https://api.ibubbl.com/v1/messages/${encodeURIComponent(messageId)}/unsend`,
{
method: "POST",
headers: { Authorization: `Bearer ${process.env.IBUBBL_API_KEY}` },
signal: AbortSignal.timeout(10_000),
},
);
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.detail?.error}`);
// 202: the Undo Send is on its way; 200: already unsent or being unsent.
console.log(res.status, data.unsend_status);
import os
import urllib.parse
import requests
API_KEY = os.environ["IBUBBL_API_KEY"]
message_id = "8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b"
res = requests.post(
f"https://api.ibubbl.com/v1/messages/{urllib.parse.quote(message_id, safe='')}/unsend",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['detail']['error']}")
# 202: the Undo Send is on its way; 200: already unsent or being unsent.
print(res.status_code, data["unsend_status"])
{
"id": "8b3a4e72-1c2d-4e5f-9a0b-2c3d4e5f6a7b",
"direction": "outbound",
"created_at": "2026-11-05T15:04:10.112730Z",
"status": "read",
"to": "+14155551234",
"body": "",
"contact_id": "c8a1f4e2-3b9d-4f7c-a8e5-1d2c3b4a5e6f",
"conversation_id": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
"conversation_kind": "one_to_one",
"chat_guid": null,
"channel": "imessage",
"sent_at": "2026-11-05T15:04:12.381Z",
"held_until": null,
"held_reason": null,
"effect": null,
"reply_to_message_id": null,
"attachments": [],
"edited_at": null,
"edit_count": 0,
"edit_status": null,
"unsend_status": "pending",
"unsent_at": null
}
{
"detail": {
"error": "unsend_window_expired",
"message": "This message can no longer be unsent."
}
}
Responses
202 Accepted The Undo Send is on its way. The body is the message withunsend_status: "pending".
| Field | Description |
|---|---|
body | "" at once (for a dashboard message with a link preview, the link alone until the card is gone too). The text comes back if the Undo Send fails. |
unsend_status | pending now; then unsent when it reaches the recipient, or failed if it doesn’t. |
unsent_at | When it was unsent (UTC); null until then. |
{
"detail": {
"error": "unauthorized",
"message": "Invalid or revoked API key"
}
}
message values: Authorization Bearer token required, API key required (use Authorization: Bearer ib_pk_…), Invalid API key format, Customer account not found.
403 Forbidden
{
"detail": {
"error": "forbidden",
"message": "Account is suspended"
}
}
message is then Account is cancelled). Every API-key endpoint returns this.
404 Not Found
{
"detail": {
"error": "not_found",
"message": "Message not found"
}
}
{
"detail": {
"error": "edit_in_flight",
"message": "An edit is being dispatched; wait for it to complete before unsending."
}
}
message.edited (usually a few seconds), then unsend. Nothing changed.
422 Unprocessable Entity
{
"detail": {
"error": "multi_part",
"message": "This message has more than one part (text and files, or several files), so it can't be unsent through the API."
}
}
error is one of:
invalid_target: the message is one you received. Only messages you sent can be unsent.sms_not_supported: the message went out by SMS (RCS included), where messages can’t be unsent.not_sent_yet: the message is stillpendingorqueued. Cancel it instead.not_unsendable: the message failed, was cancelled or expired, or iMessage never confirmed it.unsend_window_expired: more than 110 seconds sincesent_at.multi_part: the message has files and text, or several files. Unsending part of a message is available in the dashboard only.
{
"detail": {
"error": "rate_limited",
"message": "Too many conversation actions; wait 12s (limit 300 a minute per account)."
}
}
Retry-After header’s seconds, then send the same request again.Authorizations
Bearer API key. Format: Authorization: Bearer ib_pk_<64 hex> (70 characters). Generate keys from Dashboard → Settings → API Access.
Path Parameters
Response
Already unsent or being unsent; nothing changed.
Unique message identifier (UUID).
outbound = sent from your line (through the API, the dashboard or an automation); inbound = received from a contact. An inbound message has status delivered, or read once it has been read in the dashboard.
inbound, outbound ISO 8601 UTC timestamp, with microseconds and a Z, of when iBubbl recorded the message. It never changes, so it is what GET /v1/messages sorts and filters by; pass it back as created_after / created_before unchanged.
"2026-05-17T14:23:45.123456Z"
Lifecycle state. pending = accepted and on its way out; it may be waiting for the contact's working hours or the line's hourly limit for new contacts (see held_until). queued = parked by a capacity hold (hourly_cap_hit / line_offline), retried automatically. sent / delivered / read = delivery progression. failed = the send failed — see webhook message.failed for the reason; it can follow sent (or a read with no confirmed delivery) when iMessage reports the send failed after accepting it (failed_reason imessage_undeliverable / imessage_error:<code>), and such a message can still move to delivered / read if Apple later confirms it. expired = still queued after an hour, so dropped; it will not send. cancelled = stopped in the dashboard before it was sent; it will not send (webhook message.cancelled).
queued, pending, sent, delivered, read, failed, expired, cancelled The message text as sent.
The files on this message, in the order they were sent: sent with attachments, from the dashboard or an automation, or received from the contact. Empty when there are none. File contents and URLs are not returned.
Show child attributes
Show child attributes
The contact's phone number (E.164) for 1:1 messages: the destination of an outbound message, and the sender of an inbound one. Null for group messages — the group is identified by chat_guid instead.
"+14155551234"
ID of the contact this message was sent to. For groups, this is the 'primary' participant the message was addressed to (the first participant in participant_phones on a new group create); the conversation's full participant list is available via the conversation.
ID of the conversation this message belongs to. Stable for the lifetime of the conversation; use it to fetch the thread or correlate webhook events.
one_to_one for sends to a single contact, group for iMessage groups (2+ participants in addition to your iBubbl line).
one_to_one, group Opaque identifier for the group chat (e.g. any;+;<hex>). Returned for group messages — use it to address later messages to the same group via the chat_guid request shape. Null for one_to_one messages, and for a brand-new group until the group has been created in iMessage (that happens when the first message goes out, which can wait for sending hours); poll GET /v1/messages/{id} to see it fill in. It changes when a participant is added to the group.
"any;+;067ace6caf6c43aaa2f7d643975e15ea"
How the message travelled: imessage, or sms (a text, including RCS). For an outbound message, how it actually went out (sms when the recipient couldn't be reached on iMessage); null until it has been sent. For an inbound message, how it arrived; null when that wasn't recorded.
imessage, sms ISO 8601 UTC timestamp. Set when the message is accepted, then replaced by the actual send time once it goes out. Use status (sent / delivered / read), not sent_at, to tell whether it has actually gone out.
"2026-05-17T14:23:45.123Z"
While a pending message is being held, the expected time (ISO 8601 UTC) it will go out: the next opening of the contact's working hours; for hourly_limit, an estimate of when a slot frees. Recomputed within about 10 seconds. Null when the message is not held, when held_reason is working_hours but no sending day is enabled, and when it is hourly_limit with no estimate.
"2026-10-08T16:00:00+00:00"
Why a pending message is being held right now: working_hours (outside the contact's working hours) or hourly_limit (the line has started its limit of new contacts for this hour; the message goes out by itself when a slot frees, at about held_until). Null when it is not held.
working_hours, hourly_limit The iMessage send effect requested for this message, or null. It shows on the recipient's device only when channel is imessage.
slam, loud, gentle, invisible, echo, spotlight, balloons, confetti, love, lasers, fireworks, celebration, shooting_star The ID of the message this one quotes as an inline reply, or null. The quote shows on the recipient's device only when channel is imessage.
ISO 8601 UTC timestamp of the latest edit that reached the recipient: one of yours (POST /v1/messages/{id}/edit, or the dashboard), or, on an inbound message, the contact's own edit. Null when it was never edited.
"2026-05-17T14:25:00.000000Z"
How many of your edits reached the recipient. iMessage allows five per message. Always 0 on an inbound message.
0 <= x <= 5pending = your latest edit is on its way (body already shows the new text); failed = it didn't reach the recipient, and body is back to the text they have (webhook message.edit_failed); edited = the message was edited. Null when it never was.
pending, edited, failed pending = your Undo Send is on its way; unsent = the whole message was unsent (by you, or by the contact on an inbound message) and body is empty; partly_unsent = part of it was (its text, a link preview or a file); failed = your Undo Send didn't happen and the recipient still has the message (webhook message.unsend_failed). Null when nothing was unsent.
pending, unsent, partly_unsent, failed ISO 8601 UTC timestamp of when the message (or the latest part of it) was unsent. Null unless unsend_status is unsent or partly_unsent.
"2026-05-17T14:24:10.000000Z"