> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Undo or send a held message now

> Cancel a reply in its Undo window, or send a held message now, optionally skipping the per-contact queue (passFifo).

> [!WARNING]
>
> **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste into it.
> There is no sandbox: `send_now` sends a real message, and `cancel` cancels a real one.

## What this endpoint does

A message can be **held** before it goes out:

* **In its Undo window.** A reply sent with an Undo delay, or an Autopilot reply your workspace holds for Undo.
* **In the per-contact queue.** It waits behind an earlier message to the same contact on the same line.
  See [Message order (FIFO) and Send now](https://docs.tuco.ai/api-reference/message-order.md).

This endpoint acts on one held message:

| `action` | What happens |
| - | - |
| `cancel` | The message never goes out. If it reserved a daily-limit slot, the slot is given back. |
| `send_now` | The message goes now instead of at the end of its Undo window. |
| `send_now` + `passFifo: true` | It also skips the queue: it goes even though an earlier message to the same contact is still waiting. |

## Authentication

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

You can act on a message **you sent** (with this API key's user) in this workspace. An **Autopilot** reply
held for Undo can be undone or sent now with any API key of that workspace.

## Request body

**messageId** `string` *required*

The id of the held message (the `_id` returned when you sent it, or from [`GET /api/messages`](https://docs.tuco.ai/api-reference/endpoint/get-messages)).

**action** `string` *required*

`cancel` or `send_now`.

**passFifo** `boolean` (default: false)

Only with `send_now`. Lets this one message skip the per-contact queue. It also works on a message the queue
is holding after its Undo window ended (`rescheduleReason: "fifo:serial_lock_blocked"`). It is **refused on a
first message**: if nothing has been delivered to this contact on this line yet, the message keeps waiting and
the response says `fifo.passFifoRefused: "first_message"`.

## Example

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/unibox/held-reply" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "messageId": "6b02fb399a3f70b73d69cf2d", "action": "send_now", "passFifo": true }'
```

## Responses

```json Cancelled theme={null}
{ "ok": true, "state": "cancelled" }
```

```json Sending now theme={null}
{ "ok": true, "state": "sending" }
```

```json Send now + passFifo theme={null}
{
  "ok": true,
  "state": "sending",
  "fifo": {
    "blocked": false,
    "behind": null,
    "behindDueAt": null,
    "passFifo": true,
    "checked": true
  }
}
```

```json passFifo refused (first message) theme={null}
{
  "ok": true,
  "state": "held",
  "fifo": {
    "blocked": true,
    "behind": "6b02fb2a9a3f70b73d69cf21",
    "behindDueAt": null,
    "passFifo": true,
    "passFifoRefused": "first_message",
    "checked": true
  }
}
```

```json Too late theme={null}
{ "ok": false, "state": "too_late", "status": "sent" }
```

**ok** `boolean`

`true` when the action was applied.

**state** `string`

`cancelled`, `sending` (it goes now), `held` (it still waits behind an earlier message), or `too_late`
(it was already being sent, or already sent).

**fifo** `object`

Only when `passFifo` was sent. `blocked`: still waiting behind an earlier message. `behind`: that message's id.
`behindDueAt`: when it is due, if it is planned for a set time. `passFifoRefused`: `first_message` when skipping
was refused. `checked`: `false` if the check could not run (then `blocked` is unknown).

**status** `string`

On `too_late` or `cancelled` from an earlier call: the message's current status.

## Errors

| Status | When |
| - | - |
| `400` | `messageId` missing or not a valid id, or `action` is not `cancel` / `send_now`. |
| `401` | Missing or invalid API key. |
| `404` | `Reply not found`: no held message with this id that you can act on in this workspace. |

> [!NOTE]
>
> Cancel and send now are **atomic**: they only act while the message is still waiting. If Tuco has already started
> sending it, the answer is `state: "too_late"` and the message goes out (or went).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.