> ## 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.

# Send Message

> Send an iMessage, SMS, or email to a contact — the core automation endpoint. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON.

> [!WARNING]
>
> **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste
> into it. There is no sandbox — a request from this page sends a real message from one of your lines.

> [!NOTE]
>
> This is the primary endpoint for automation tools like **GetSales**, **n8n**, **Make**, or your own backend.
> One call = one message. Tuco handles retries, delivery verification, and fallback internally.

```bash Minimal theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hi from Tuco.",
    "recipientPhone": "+12025551234"
  }'
```

```bash Send window, weekdays theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Morning! Quick question about your quote.",
    "recipientPhone": "+12025551234",
    "sendWindowStart": "09:00",
    "sendWindowEnd": "18:00",
    "timezone": "America/New_York",
    "allowedDaysOfWeek": [1, 2, 3, 4, 5]
  }'
```

```bash Follow-up, keep the gap theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Just checking you saw my last note",
    "recipientPhone": "+12025551234",
    "respectGap": true
  }'
```

```bash Gap + skip if replied theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Still interested? Happy to hold your slot.",
    "recipientPhone": "+12025551234",
    "respectGap": true,
    "skipIfReplied": true,
    "sendWindowStart": "09:00",
    "sendWindowEnd": "18:00",
    "timezone": "America/New_York"
  }'
```

```json 201 Sent theme={null}
{
  "success": true,
  "status": "sent",
  "leadId": "69b2c41d352a78479d2c623b",
  "message": {
    "_id": "69b344bc6dae1d942ece4d0e",
    "message": "Hi from Tuco.",
    "messageType": "imessage",
    "direction": "sent",
    "recipientPhone": "+12025551234",
    "fromLineId": "69ab427ac1feb77d7f46462e",
    "leadId": "69b2c41d352a78479d2c623b",
    "status": "sent",
    "createdAt": "2026-10-13T16:57:58.468Z",
    "updatedAt": "2026-10-13T16:58:00.016Z",
    "sentAt": "2026-10-13T16:58:00.016Z"
  }
}
```

```json 201 Held theme={null}
{
  "success": true,
  "status": "scheduled",
  "leadId": "6ace9f58e350b3be067aef80",
  "message": {
    "_id": "6ace9f59e350b3be067aef81",
    "message": "Morning! Quick question about your quote.",
    "messageType": "imessage",
    "direction": "sent",
    "recipientPhone": "+12025551234",
    "fromLineId": "6ace9f5622264a6eecd4b333",
    "leadId": "6ace9f58e350b3be067aef80",
    "status": "scheduled",
    "scheduledDate": "2026-10-14T13:00:00.000Z",
    "settings": {
      "timezone": "America/New_York",
      "sendWindowStart": "09:00",
      "sendWindowEnd": "18:00",
      "allowedDaysOfWeek": [1, 2, 3, 4, 5]
    },
    "createdAt": "2026-10-13T23:15:05.519Z",
    "updatedAt": "2026-10-13T23:15:05.771Z"
  }
}
```

```json 200 Skipped theme={null}
{
  "success": true,
  "skippedOnly": true,
  "skipReason": "recipient_replied",
  "skipMessage": "Skipped: this contact already replied in your workspace at any time. The skipIfReplied gate prevented this send.",
  "repliedAt": "2026-10-13T16:59:48.131Z",
  "message": null,
  "leadId": "6ace637e30e2d7468c7bf397"
}
```

```json 400 Window theme={null}
{
  "error": "sendWindowStart must be earlier than sendWindowEnd. Overnight windows (e.g. \"22:00\"–\"06:00\") are not supported; use \"00:00\"–\"23:59\" to send at any hour.",
  "code": "INVALID_SEND_WINDOW"
}
```

```json 400 Timezone theme={null}
{
  "error": "\"EST\" is an abbreviation with a fixed offset that ignores daylight saving. Use an IANA timezone name such as \"America/New_York\" or \"Europe/London\", or omit timezone to use your workspace timezone.",
  "code": "INVALID_TIMEZONE"
}
```

```json 400 Days theme={null}
{
  "error": "allowedDaysOfWeek must be an array of whole numbers from 0 (Sunday) to 6 (Saturday), e.g. [1,2,3,4,5].",
  "code": "INVALID_ALLOWED_DAYS"
}
```

## Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

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

***

## Request body

**message** `string`

The text content to send. **Required unless** `attachmentUrls` is provided (you can send attachments only, or message + attachments).

**Template variables** are filled in **at send time** — on every send attempt, against the line that actually sends the message (so retries, scheduled or send-window-deferred messages, and round-robin all name the right line) and the contact's current data. The same variables campaigns use:

| Variable | Filled with |
| - | - |
| `{line_first_name}` | First name of the sending line |
| `{line_name}` | Sending line's first + last name |
| `{line_email}` · `{line_phone}` | Sending line's email · phone |
| `{firstName}` `{lastName}` `{companyName}` `{email}` `{phone}` `{jobTitle}` `{notes}` | The contact's fields |
| `{cf:Field Name}` | A contact custom field |
| `{yourVariable}` | Your workspace variable's default (Settings → Variables) |

Single `{x}` or double `{{x}}` braces, any case. Add a fallback after a pipe: `{firstName|there}`. Variables work inside links too (`https://cal.com/{line_first_name}`). Anything in braces that is **not** one of these is sent exactly as written.

**A blank is never sent.** If a variable has no value and no fallback, the request is rejected: an empty `{firstName}` / `{lastName}` → `400 MALFORMED_NAME_TEMPLATE`; any other → `400 TEMPLATE_VARIABLE_UNRESOLVED` (the response lists them in `unresolvedVariables`). Text you already filled in yourself is unaffected; an unfilled token from another tool (e.g. `{{contact_name}}`, `{name}`) or a greeting whose name expanded to nothing (`"Hey , …"`) is still rejected with `MALFORMED_NAME_TEMPLATE`.

```json theme={null}
{ "recipientPhone": "+14155550123", "message": "Hey {firstName|there}, {line_first_name} here — grab a time: https://cal.com/{line_first_name}" }
```

**attachmentUrls** `string[]`

Optional array of URLs (max 2, max 25 MB each). When provided, `message` can be empty. Supported formats: images (PNG, JPG, GIF, WebP, HEIC), video (MP4, MOV), audio (MP3, M4A, WAV, AAC, OGG, CAF), and PDF. Supported sources: any public URL, UploadThing/Blob URLs that belong to your workspace. To send audio as a native iMessage voice note (the waveform bubble), add `voiceNote: true`. The audio must be a **direct, publicly reachable file URL** — a YouTube or Drive page is rejected with a 400. Easiest source is **Leads → Uploads** (`/leads?tab=uploads`). See [Voice note requirements](https://docs.tuco.ai/api-reference/endpoint/send-with-attachments.md#voice-note-requirements).

With an attachment or voice note, you get `status: "sent"` right away and it starts sending. If it fails, you get a `message.failed` webhook for the same `message._id`.

> [!TIP]
>
> Sending the same attachment URL repeatedly (e.g. a promo video in an automation)? Tuco caches attachments per line — the second send skips the download and upload, making it significantly faster.

**attachmentNames** `string[]`

Optional display names for the attachments, aligned 1:1 with `attachmentUrls`. Omit and Tuco uses the filename from the URL.

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

Send a single audio attachment as a **native iMessage voice note** (the waveform bubble) instead of a generic audio file. Tuco transcodes the audio for you. Requires exactly one audio attachment in `attachmentUrls` — see [Send with Attachments](https://docs.tuco.ai/api-reference/endpoint/send-with-attachments.md#voice-note-requirements) for the full rules.

**recipientPhone** `string`

**The phone number to text, in E.164 format** (e.g. `"+12025551234"`). This is how you address
almost every send — you do not need a `leadId`. Tuco matches an existing lead on this number, or
creates one under the **Quick Sends** list.

Required unless you pass `leadId` or `recipientEmail`.

**leadId** `string`

Send to an existing lead using their stored contact details. When provided together with
`recipientPhone`, the body's phone number is the send-to address and the lead is used for linking.

Required unless you pass `recipientPhone` or `recipientEmail`.

**recipientEmail** `string`

> [!WARNING]
>
> **Use `recipientPhone` unless you specifically need this.** An email address only reaches someone
> over iMessage if that exact address is registered to their Apple account, which is uncommon and
> impossible to assume. Addressing by phone number is what works.

Only useful in two cases: `messageType: "email"`, or iMessage to a contact you already know is
reachable at that Apple ID. Required unless you pass `recipientPhone` or `leadId`.

**messageType** `string` (default: imessage)

Channel to use. When omitted, defaults to `"imessage"`.

| Value | Channel | Addresses tried (from lead) |
| - | - | - |
| `"imessage"` | iMessage via device relay | phone → altPhone1-3 → email → altEmail1-3 |
| `"sms"` | SMS via Twilio | phone → altPhone1-3 only |
| `"email"` | Email | email → altEmail1-3 only |

**fromLineId** `string`

Tuco line ID to send from. **Optional** — when omitted, Tuco round-robins
across your workspace's active lines automatically.

**recipientName** `string`

Display name for the recipient. Derived from the lead when omitted.

### Alternate contact fields

Stored on the lead (created or found). The worker tries these in priority
order when the primary address fails iMessage availability.

**altPhone1** `string`

Alternate phone number 1

**altPhone2** `string`

Alternate phone number 2

**altPhone3** `string`

Alternate phone number 3

**altEmail1** `string`

Alternate email 1

**altEmail2** `string`

Alternate email 2

**altEmail3** `string`

Alternate email 3

### Scheduling & time window

Control **when** the message is sent. All fields are optional.
When omitted, the message sends immediately (subject to line limits and device gaps).

**scheduledDate** `string`

ISO 8601 timestamp to send in the future (e.g. `"2026-10-15T14:30:00Z"`). The
response `status` is `"scheduled"`. If you also set a send window and this time
falls outside it, the message is moved to the next time the window is open.
A value that can't be parsed returns `400`.

**sendWindowStart** `string`

Earliest time to send, `HH:mm` 24-hour format (e.g. `"09:00"`), inclusive. Set
**both** `sendWindowStart` and `sendWindowEnd` — if only one is sent, the window is
ignored. Outside the window the request still returns `201` with
`status: "scheduled"`; the message is held until the window opens. Use
`"00:00"`–`"23:59"` for any hour. Anything that isn't `HH:mm` returns `400`.

**sendWindowEnd** `string`

Latest time to send, `HH:mm` (e.g. `"17:00"`). The end is exclusive, and it must be
later than the start. An overnight window such as `"22:00"`–`"06:00"` returns
`400 INVALID_SEND_WINDOW`; use `"00:00"`–`"23:59"` to send at any hour.

**timezone** `string`

IANA timezone for the send window (e.g. `"America/New_York"`). **Optional.** When
omitted, your workspace timezone is used (or `America/New_York` if the workspace
has none). Use a full name — an abbreviation like `"EST"` or an unknown name
returns `400 INVALID_TIMEZONE` when a send window is set. `"UTC"` is accepted.
The timezone is only used together with a send window.

**allowedDaysOfWeek** `number[]`

Days when sending is allowed, as whole numbers. `0` = Sunday, `6` = Saturday.
Example: `[1,2,3,4,5]` for weekdays only. An empty array means every day; any
other value returns `400 INVALID_ALLOWED_DAYS`. **Only applies together with
`sendWindowStart` and `sendWindowEnd`** — a day list without hours is ignored. On a
day that isn't allowed, the message waits for `sendWindowStart` on the next allowed
day. See [Send window and allowed days](#send-window-and-allowed-days).

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

Keep the wait between follow-ups to the same contact. When `true`, and an earlier
message to this contact went out late, this message is held so the original spacing
is preserved: it waits until the previous message's actual send time plus the gap
between your two API calls. Works on its own — no send window or workspace setting
needed. Accepts `true` or `"true"`; any other value is treated as `false`. While
held, the response `status` is `"scheduled"`. See
[Keep the wait between follow-ups](#keep-the-wait-between-follow-ups).

### Fallback & advanced

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

When `true`, if the message ends in `failed` status (technical error after
retries), Tuco sends a fallback SMS via your configured fallback number.
If no fallback is configured on the workspace the request is **still accepted** —
the iMessage send proceeds and simply has no SMS to fall back to. Check
[`GET /api/workspace/fallback-config`](https://docs.tuco.ai/api-reference/endpoint/fallback-config)
first if you need the fallback to actually fire.

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

When `true`, Tuco **skips the iMessage availability check entirely** and sends
the message straight via your workspace's configured fallback — Twilio, GHL, or
a custom webhook (Settings → *When iMessage isn't available*). Use it when you
already know the recipient isn't on iMessage, or you simply want SMS.

The send never touches iMessage, so it does **not** consume the line's daily
cap or the availability-check budget, and the response status is `"fallback"`.

If no fallback is configured — or the fallback dispatch fails (e.g. a bad Twilio
from-number) — the message is **not** delivered: the response returns
`"success": false` with a channel-tagged `error`, and the message is recorded
with `"fallbackSmsStatus": "failed"`. The request itself still succeeds — read the
`success` flag in the body rather than relying on the status code.

Unlike `sendFallbackSmsOnFailed` (which is *reactive* — fallback only after an
iMessage send fails), `forceFallback` is *proactive*: it never attempts iMessage
in the first place.

**skipIfReplied** `string | boolean` (default: false)

Workspace-level reply gate. When set, Tuco **suppresses this send if the
contact has already replied in your workspace**.

* `false` / `"false"` / omitted → always send (default, backward compatible)
* `true` / `"true"` → skip if the contact has **ever** replied
* a window string → skip only if they replied **within** that window:
  `"1m"`, `"1h"`, `"1d"`, `"2d"`, `"5d"`, `"7d"`, `"14d"`, `"1mo"`, `"1yr"`
  (`m`=minute, `h`=hour, `d`=day, `w`=week, `mo`=30 days, `yr`=365 days)

Scope is your **workspace** — a reply to *any* of your lines counts (not just
the sending line). The check never crosses workspaces. On a skip, **no message
is created** and the API returns `200` with `skippedOnly: true` (see
[Skip if the contact already replied](#skip-if-the-contact-already-replied)).
The check runs again right before a queued message sends: if the contact replied
while it was waiting, it is cancelled instead of sent.
An unrecognized value returns `400 INVALID_SKIP_IF_REPLIED`.

**batchId** `string`

Free-form string to group related messages for reporting.

**correlationId** `string`

Optional tracing ID. If omitted, Tuco generates one (`app_…`). The same ID
is preferred from the `x-correlation-id` request header. It flows through
every internal log event for this send so you can grep one ID and see the entire
request → gate → send → webhook chain. See
[API Overview → Correlation IDs](https://docs.tuco.ai/api-reference/introduction.md#correlation-ids-request-tracing).

> [accordion] Request headers
>
> Headers Tuco recognizes in addition to `Authorization`.
>
> | Header | Purpose |
> | - | - |
> | `x-correlation-id` | Request-scoped tracing ID (preferred over body field). Echoed back in logs under `correlationId`. |
> | `x-execution-id` | GHL workflow execution ID. Only set when calling from a GHL workflow context. |
> | `x-ghl-workflow-id` | GHL workflow definition ID. Pairs with `x-execution-id`. |
> | `Idempotency-Key` | When supplied, Tuco caches the response and replays it on retry within the idempotency window. Use one unique key per logical send. |

***

## Examples

Create or import a lead first using [`POST /api/leads`](https://docs.tuco.ai/api-reference/leads), then send using `leadId` as shown below.

```bash Minimal using leadId (defaults to iMessage) theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hi, this is a test from Tuco.",
    "leadId": "667f1f77bcf86cd799439012"
  }'
```

Need a `leadId` first? Create one with [`POST /api/leads`](https://docs.tuco.ai/api-reference/leads), then use the returned `leadId` in this request.

```bash HubSpot lead theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hi from Tuco.",
    "leadId": "667f1f77bcf86cd799439013",
    "hsContactId": "120001",
    "hsPortalId": "991001"
  }'
```

```bash GHL lead theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hi from Tuco.",
    "leadId": "667f1f77bcf86cd799439014",
    "ghlContactId": "ghl_contact_001",
    "ghlLocationId": "eL7DD22BdZ0rismu7qCA"
  }'
```

```bash With attachments theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Here is the file.",
    "leadId": "667f1f77bcf86cd799439012",
    "attachmentUrls": ["https://example.com/doc.pdf"]
  }'
```

```bash GoHighLevel webhook (raw payload) theme={null}
# The exact body GoHighLevel's "Webhook" workflow action posts. You only fill in
# customData.message — Tuco derives the recipient + GHL identity from the rest.
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "KWqc16yBbIV7hLfiRTse",
    "full_name": "Matheus Maia",
    "email": "alex@example.com",
    "phone": "+13055550100",
    "location": { "id": "57m52yUR4RkI2k1VuHhL" },
    "customData": { "message": "Hi Matheus" }
  }'
```

```bash Send window, weekdays only theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Morning! Quick question about your quote.",
    "recipientPhone": "+12025551234",
    "sendWindowStart": "09:00",
    "sendWindowEnd": "18:00",
    "timezone": "America/New_York",
    "allowedDaysOfWeek": [1, 2, 3, 4, 5]
  }'
```

```bash Follow-up that keeps its gap theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Just checking you saw my last note",
    "recipientPhone": "+12025551234",
    "respectGap": true
  }'
```

```bash Follow-up: keep the gap, skip if they replied theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Still interested? Happy to hold your slot.",
    "recipientPhone": "+12025551234",
    "respectGap": true,
    "skipIfReplied": true,
    "sendWindowStart": "09:00",
    "sendWindowEnd": "18:00",
    "timezone": "America/New_York"
  }'
```

***

## Send straight from a GoHighLevel webhook

You can point a GoHighLevel **Workflow → Webhook** action directly at this endpoint —
no GHL Marketplace app or action secret required, just your Tuco API key in the
`Authorization` header. GHL's Webhook action already includes the full contact
payload; Tuco reads GHL's native field names so **the only thing you map in Custom
Data is `message`**.

**1. Add a Webhook action to your workflow**

Method `POST`, URL `https://app.tuco.ai/api/messages`.

**2. Add the auth header**

`Authorization` = `Bearer tuco_xxxxxxxxxxxxx`.

**3. Add Custom Data**

Set `message` (required). Optionally add `lineId` (pin a sending line — otherwise
Tuco round-robins) and `attachmentUrls` (a single URL or comma-separated list).

Tuco auto-maps GHL's native fields onto the canonical request fields. **Custom Data
always wins** — set any field there to override what's derived from the contact:

| Canonical field | Filled from (Custom Data first, then GHL native) |
| - | - |
| `message` | `customData.message` |
| `fromLineId` | `customData.lineId` |
| `attachmentUrls` | `customData.attachmentUrls` (string or CSV → array) |
| `recipientPhone` | `customData.recipientPhone` → top-level `phone` |
| `recipientEmail` | `customData.recipientEmail` → top-level `email` |
| `recipientName` | `customData.recipientName` → `full_name` → `first_name` + `last_name` |
| `ghlContactId` | `customData.ghlContactId` → `contact_id` |
| `ghlLocationId` | `customData.ghlLocationId` → `location.id` |
| `contactOwnerEmail` | `customData.contactOwnerEmail` → `user.email` |

> [!NOTE]
>
> This mapping is **additive and backward compatible** — it only fills a field you did
> not already send. Existing integrations that post canonical fields (`recipientPhone`,
> `ghlContactId`, …) are completely unaffected.

> [!WARNING]
>
> If `{{contact.phone}}` is empty on the contact, the request fails with
> `missing_recipient`. Make sure the contact has a phone or email before the webhook fires.

***

## Response

The API always returns **`201`** when the message is successfully created.
The `status` field tells you what happens next.

> [!TIP]
>
> **Pre-send checks are never errors.** Line limits, time windows, device gaps,
> and contact gaps cause `status: "pending"` or `"scheduled"` — the message is
> accepted and will send when conditions are met.

### Success (`201 Created` or `200 OK` when duplicate lead used)

```json theme={null}
{
  "success": true,
  "status": "sent",
  "message": {
    "_id": "69b344bc6dae1d942ece4d0e",
    "message": "Here's your document.",
    "messageType": "imessage",
    "status": "sent",
    "fromLineId": "69ab427ac1feb77d7f46462e",
    "recipientPhone": "+919876543210",
    "recipientEmail": "jane@example.com",
    "recipientName": "Jane Doe",
    "leadId": "69b2c41d352a78479d2c623b",
    "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG",
    "createdAt": "2026-03-12T22:57:00.856Z",
    "updatedAt": "2026-03-12T22:57:02.892Z",
    "sentAt": "2026-03-12T22:57:02.892Z",
    "externalMessageId": "5CA93911-F0FE-4D1F-8D8C-1E3495A124F6"
  },
  "leadId": "69b2c41d352a78479d2c623b",
  "ghlContactId": "aMUQn0u0Z7cw0NQ7tJ5R",
  "ghlLocationId": "eL7DD22BdZ0rismu7qCA",
  "hsPortalId": null,
  "hsContactId": null
}
```

When the recipient was matched to an existing lead (duplicate), the API returns **`200`** with `duplicateOnly: true`, `existingLeadIds`, and `leadIds` so your automation can continue without treating it as an error.

**success** `boolean`

`true` when the message was created.

**status** `string`

Current status of the message. See the status table below.

**message** `object`

The full message document. Key fields:

**Message fields**

**\_id** `string`

Unique message ID

**message** `string`

Body text

**messageType** `string`

Channel (`imessage`, `sms`, `email`)

**status** `string`

Lifecycle status

**fromLineId** `string`

Line used to send

**recipientPhone** `string`

Recipient phone

**recipientEmail** `string`

Recipient email

**leadId** `string`

Linked lead ID

**scheduledDate** `string`

When the message will send (if scheduled)

**sentAt** `string`

When actually sent

**deliveredAt** `string`

When delivery confirmed

**createdAt** `string`

Creation timestamp

### Accepted but held

When a send window, an allowed-day rule or `respectGap` holds the message, the request
still succeeds. `status` is `"scheduled"` and `message.scheduledDate` is when it will
be released.

```json HTTP 201 — outside the send window, held until it opens theme={null}
{
  "success": true,
  "status": "scheduled",
  "leadId": "6ace9f58e350b3be067aef80",
  "message": {
    "_id": "6ace9f59e350b3be067aef81",
    "message": "Morning! Quick question about your quote.",
    "messageType": "imessage",
    "direction": "sent",
    "recipientPhone": "+12025551234",
    "fromLineId": "6ace9f5622264a6eecd4b333",
    "leadId": "6ace9f58e350b3be067aef80",
    "status": "scheduled",
    "scheduledDate": "2026-10-14T13:00:00.000Z",
    "settings": {
      "timezone": "America/New_York",
      "sendWindowStart": "09:00",
      "sendWindowEnd": "18:00",
      "allowedDaysOfWeek": [1, 2, 3, 4, 5]
    },
    "createdAt": "2026-10-13T23:15:05.519Z",
    "updatedAt": "2026-10-13T23:15:05.771Z"
  }
}
```

`message.settings` echoes the window Tuco stored: the resolved timezone, and
`allowedDaysOfWeek` as numbers.

### Status values

| Status | Meaning | Is it an error? |
| - | - | - |
| `"sent"` | Message sent immediately (sync path) | No |
| `"pending"` | Created, worker will process. Line limits / time window / device gap may delay it. | **No** — it will send when checks pass |
| `"scheduled"` | Held until `message.scheduledDate`: your own `scheduledDate`, a send window or allowed-day rule, a `respectGap` hold, a line limit, or a retry | **No** |
| `"cancelled"` | A queued message that was dropped before sending — for example `skipIfReplied` was set and the contact replied while it waited | **No** |
| `"fallback"` | Recipient has no iMessage; fallback SMS sent if configured | **No** (business rule) |
| `"failed"` | All retries exhausted or availability API error | Yes (technical) |

> [!NOTE]
>
> `"pending"` and `"scheduled"` mean the message is accepted and queued. The worker sends it when:
>
> * **Time window** is satisfied (inside `sendWindowStart`–`sendWindowEnd`)
> * **Allowed day** is satisfied (today is in `allowedDaysOfWeek`)
> * **Follow-up gap** has passed (only when `respectGap` is `true`)
> * **Line limits** reset (daily total or new conversations limit)
> * **Device gap** is met (default 30s between sends from same device)
> * **Contact gap** is met (default 45s between first messages to different contacts on same line)
>
> None of these cause an error response.

***

## Duplicate protection

Tuco automatically blocks duplicate sends — no header required. Two POSTs with
identical `(workspaceId, recipientPhone, recipientEmail, message)` within
**15 minutes** are collapsed: the second one returns `200` with the original
message and **does not fire a new send**.

```json HTTP 200 — duplicate caught theme={null}
{
  "success": true,
  "duplicateOnly": true,
  "duplicateMessage": "Same message text already sent to this contact 42s ago — returning existing message instead of sending again",
  "message": { /* the original sibling message doc */ },
  "leadId": "..."
}
```

Branch on `duplicateOnly === true` and treat it as a no-op success. The
`message._id` in the response is the original send, so your CRM workflow can
keep moving without re-sending.

> [!TIP]
>
> This works for concurrent firings (the most common cause of accidental
> duplicates — an integration retrying within milliseconds) AND for upstream
> retries up to 15 minutes apart. The guard is built on an atomic Mongo write,
> so concurrent identical POSTs cannot both proceed.

> [!NOTE]
>
> **Failed sends:** if your first send ended in `status: "failed"` and you
> immediately retry with the same body within 15 minutes, you'll get the failed
> sibling back with `duplicateOnly: true`. To force a fresh send: change the
> body or wait 15 minutes.

For deeper detail, edge cases, and ops events, see
[Atomic Duplicate Guard](https://docs.tuco.ai/imessage-double-send-guard.md).

`Idempotency-Key` is still supported and runs **before** the dedup guard.
Use it when your client controls retries — it gives you a 24-hour window
keyed on the exact request rather than on body content.

***

## Skip if the contact already replied

Set `skipIfReplied` to avoid following up with a contact who has already responded
to you. Tuco checks your workspace's inbound history for this recipient (phone or
email) and, if it finds a reply, **does not create or send the message**. This is useful for drip
automations in n8n/Make/GHL where you don't want to nudge someone who already wrote
back.

### Values

| `skipIfReplied` | Behavior |
| - | - |
| omitted / `false` / `"false"` | Always send (default). |
| `true` / `"true"` | Skip if the contact has **ever** replied in your workspace. |
| `"1m"` `"1h"` `"1d"` `"2d"` `"5d"` `"7d"` `"14d"` `"1mo"` `"1yr"` | Skip only if they replied **within** that window. |

Units: `m` = minute, `h` = hour, `d` = day, `w` = week, `mo` = 30 days, `yr` = 365 days.
General form: `<number><unit>` (e.g. `"3d"`, `"36h"`). Note `"1m"` is one **minute** and
`"1mo"` is one **month**.

> [!NOTE]
>
> **Scope is your workspace, not a single line.** A reply to *any* of your lines counts —
> which line you send from doesn't matter. The check is strictly scoped to your workspace
> and never sees another workspace's replies.

### Request

```bash Skip the follow-up if they replied in the last 7 days theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Just following up — still interested?",
    "recipientPhone": "+12025551234",
    "skipIfReplied": "7d"
  }'
```

### Response when the send is skipped (`200 OK`)

No message is created. `success` is `true` (the request was handled — do **not** retry)
and `skippedOnly` distinguishes it from a real send.

```json HTTP 200 — skipped because the contact already replied theme={null}
{
  "success": true,
  "skippedOnly": true,
  "skipReason": "recipient_replied",
  "skipMessage": "Skipped: this contact already replied in your workspace within the last 7d. The skipIfReplied gate prevented this send.",
  "repliedAt": "2026-06-27T18:40:11.020Z",
  "message": null,
  "leadId": "667f1f77bcf86cd799439012"
}
```

Branch on `skippedOnly === true` and treat it as a successful no-op. When the contact
has **not** replied (or replied outside the window), the request proceeds exactly as a
normal send and returns the usual `201` response.

> [!WARNING]
>
> An unrecognized `skipIfReplied` value returns **400** with
> `code: "INVALID_SKIP_IF_REPLIED"`. Use `true`, `false`, or one of the documented
> window strings.

Every decision is logged internally (`message.api.skipped_replied`,
`message.api.skip_if_replied_passed`, `message.api.skip_if_replied_invalid`) under your
`correlationId`, so you can audit exactly why a send was or wasn't suppressed.

### A queued message is checked again before it sends

`skipIfReplied` is evaluated when you call the API **and again right before the message
is sent**. If a message is waiting — for a `scheduledDate`, a send window, a line limit,
a line that is down, or a `respectGap` hold — and the contact replies in the meantime,
the message is **cancelled** instead of sent (its status becomes `cancelled`).

With a window value such as `"1h"`, the second check looks back from the moment of
sending, not from when you made the request.

***

## Keep the wait between follow-ups

Automations usually space follow-ups out: message 1, wait, message 2. If message 1 goes
out late — held by a send window, a line limit, pacing, or a line that was briefly
down — message 2 can land right behind it and the wait you designed disappears.

Set `respectGap: true` on the follow-up to keep that wait.

### How the hold is calculated

Tuco looks at the most recent message already sent to the same contact in your
workspace and holds the new one until:

```
previous message's actual send time + (this request's time − previous request's time)
```

So the gap between your two **API calls** is preserved, measured from when the previous
message **really went out**. It does not use `scheduledDate`.

| | Request made | Actually sent |
| - | - | - |
| Message 1 | 10:00:00 | 10:07:00 (held 7 minutes) |
| Message 2, `respectGap: true` | 10:05:00 (5 minutes after message 1) | held until 10:12:00, then sent |
| Message 2, no `respectGap` | 10:05:00 | sent as soon as it is free — right behind message 1 |

### Request

```bash Follow-up that keeps its spacing theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Just checking you saw my last note",
    "recipientPhone": "+12025551234",
    "respectGap": true
  }'
```

The response is the usual `201`. When the message is being held, `status` is
`"scheduled"` and `scheduledDate` is the time it is held until:

```json HTTP 201 — held to keep the gap theme={null}
{
  "success": true,
  "status": "scheduled",
  "leadId": "6ace83280fadae5820a37ae4",
  "message": {
    "_id": "6ace83bd0fadae5820a37b01",
    "message": "Just checking you saw my last note",
    "messageType": "imessage",
    "direction": "sent",
    "recipientPhone": "+12025551234",
    "fromLineId": "6ace832115ae149cfdf83db7",
    "leadId": "6ace83280fadae5820a37ae4",
    "status": "scheduled",
    "respectGap": true,
    "scheduledDate": "2026-10-13T19:18:29.579Z",
    "createdAt": "2026-10-13T19:17:17.937Z",
    "updatedAt": "2026-10-13T19:17:18.274Z"
  }
}
```

### Without `respectGap`: a 1-minute minimum

![A three-step sequence whose first step goes out late: by default the steps go out at least a minute apart; with respectGap the full gaps are kept; a reply cancels the remaining steps with skipIfReplied](https://mintcdn.com/tucoai/SoLkNcvAIeibvkGp/images/sequence-late-step.png?fit=max\&auto=format\&n=SoLkNcvAIeibvkGp\&q=85\&s=61ac41c85104d24bb7e2528e4a906e85)

Even when you don't set `respectGap`, Tuco never lets a late message drag the next one
out right behind it. If two messages to the same contact were planned **at least 1 minute
apart** and the first one went out late, the second goes out **at least 1 minute after the
first one actually sent**. "Planned" means the `scheduledDate` you sent, or the time of
your API call.

| | Planned | Actually sent |
| - | - | - |
| Message 1 | 10:00 | 10:40 (held by a line limit) |
| Message 2, planned +15 min, no `respectGap` | 10:15 | 10:41 (1 minute after message 1) |
| Message 2, planned +30 s (bubble), no `respectGap` | 10:00:30 | 10:40, right behind message 1 |
| Message 2, `respectGap: true`, API call made at 10:15 | 10:15 | 10:55 (the full 15 minutes between the two calls) |

Messages planned less than a minute apart (a reply split into several bubbles) still go
together. A message you type in the inbox to send now, or any message after the contact
has replied, is never held. With `skipIfReplied`, a reply during the wait cancels the
next message. Set `respectGap: true` to keep the full planned gap instead.

### What to expect

* **Works without a send window.** `respectGap` needs no `sendWindowStart`,
  `sendWindowEnd` or `timezone`.
* **It is per contact, across all your lines.** The previous message can have gone out
  from a different line. Messages to other contacts are never affected.
* **The first message to a contact is never held** — there is nothing to space it from.
* **"Previous message" means the latest one sent to that contact**, whatever sent it. A
  manual reply from the inbox in between becomes the new reference point.
* **The gap is a minimum.** Held messages are released about once a minute, so the real
  spacing is the gap plus up to a minute.
* **A send window still wins.** If the hold ends outside `sendWindowStart`–`sendWindowEnd`
  (or on a day not in `allowedDaysOfWeek`), the message waits for the window to open.
* **If the earlier message went out on time, nothing changes** — the follow-up sends
  normally.
* **Combine it with `skipIfReplied`** to drop the follow-up if the contact answers while
  it is being held.
* Only `true` or `"true"` turn it on. Any other value is treated as off.

> [!WARNING]
>
> `respectGap` spaces a follow-up from a message that has **already been sent**. If the
> earlier message is still waiting when the follow-up arrives, there is nothing to measure
> from yet, so `respectGap` does not hold the follow-up. With several lines, if the
> earlier message is pinned to a line that is down (`fromLineId`)
> and the follow-up is not pinned, the follow-up can go out first on a healthy line —
> pin both to the same line, or leave both unpinned, to avoid that.

***

## Send window and allowed days

| You send | What happens |
| - | - |
| No window fields | Sends immediately (subject to line limits and pacing). |
| `sendWindowStart` + `sendWindowEnd`, inside the window | Sends immediately. |
| `sendWindowStart` + `sendWindowEnd`, outside the window | `201`, `status: "scheduled"`, held until the window next opens. |
| Only one of the two | The window is ignored. |
| No `timezone` | Workspace timezone, then `America/New_York`. |
| An unknown `timezone`, or an abbreviation like `"EST"` | `400 INVALID_TIMEZONE`. |
| `allowedDaysOfWeek` without both window times | The day list is ignored. |
| A time that isn't `HH:mm` (e.g. `"9am"`, `"25:00"`) | `400`. |
| Start not earlier than end (`"22:00"`–`"06:00"`, `"09:00"`–`"09:00"`) | `400 INVALID_SEND_WINDOW`. |
| `allowedDaysOfWeek` that isn't whole numbers `0`–`6` (e.g. `[7]`, `[1.5]`, `"monday"`) | `400 INVALID_ALLOWED_DAYS`. |

### Request

```bash Weekdays, 9am–6pm New York theme={null}
curl -X POST "https://app.tuco.ai/api/messages" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Morning! Quick question about your quote.",
    "recipientPhone": "+12025551234",
    "sendWindowStart": "09:00",
    "sendWindowEnd": "18:00",
    "timezone": "America/New_York",
    "allowedDaysOfWeek": [1, 2, 3, 4, 5]
  }'
```

Inside the window on an allowed day the response is the normal `201` with
`status: "sent"`. Outside it you get `201` with `status: "scheduled"` — see
[Accepted but held](#accepted-but-held).

### Rejected values (`400`)

```json Overnight window theme={null}
{
  "error": "sendWindowStart must be earlier than sendWindowEnd. Overnight windows (e.g. \"22:00\"–\"06:00\") are not supported; use \"00:00\"–\"23:59\" to send at any hour.",
  "code": "INVALID_SEND_WINDOW"
}
```

```json Timezone abbreviation theme={null}
{
  "error": "\"EST\" is an abbreviation with a fixed offset that ignores daylight saving. Use an IANA timezone name such as \"America/New_York\" or \"Europe/London\", or omit timezone to use your workspace timezone.",
  "code": "INVALID_TIMEZONE"
}
```

```json Unknown timezone theme={null}
{
  "error": "\"Mars/Phobos\" is not a recognized timezone. Use an IANA timezone name such as \"America/New_York\" or \"Europe/London\", or omit timezone to use your workspace timezone.",
  "code": "INVALID_TIMEZONE"
}
```

```json Bad day list theme={null}
{
  "error": "allowedDaysOfWeek must be an array of whole numbers from 0 (Sunday) to 6 (Saturday), e.g. [1,2,3,4,5].",
  "code": "INVALID_ALLOWED_DAYS"
}
```

```json Bad time format theme={null}
{
  "error": "Invalid time format. sendWindowStart and sendWindowEnd must be in HH:mm format (e.g., 09:00, 17:00)"
}
```

Day numbers sent as strings (`["1","2","3"]`) are accepted and stored as numbers.

### The window is checked again every time the message is about to send

The window you put on a message is checked when you call the API **and again each time
Tuco is about to send it**. So if something delays the message — a failed attempt that
is retried a few minutes later, a line that was briefly down, a daily or hourly limit —
and the window has closed in the meantime, the message waits for the window to open
again instead of going out late. `allowedDaysOfWeek` is applied the same way: on a day
that isn't allowed, the message waits for `sendWindowStart` on the next allowed day.

This applies to every message sent through the API that carries its own
`sendWindowStart` and `sendWindowEnd`.

These checks only run when a send window is set. Without `sendWindowStart` and
`sendWindowEnd`, `timezone` and `allowedDaysOfWeek` are ignored.

***

## Errors

Errors are returned only for **validation failures** — never for pre-send checks.

| Status | When | Example |
| - | - | - |
| `400` | Message and attachments both empty | `{ "error": "Message and attachmentUrls cannot both be empty" }` |
| `400` | Invalid `messageType` | `{ "error": "Invalid messageType. Must be email, sms, or imessage" }` |
| `400` | No active lines + no `fromLineId` | `{ "error": "No active lines in workspace..." }` |
| `400` | No recipient anywhere | `{ "error": "Either recipientEmail or recipientPhone is required..." }` |
| `400` | Unrecognized `skipIfReplied` value | `{ "error": "...", "code": "INVALID_SKIP_IF_REPLIED" }` |
| `400` | `{firstName}`/`{lastName}` has no value and no fallback, an unfilled non-Tuco token (`{{contact_name}}`), or a name expanded to nothing | `{ "error": "Malformed message: name template variable is empty...", "code": "MALFORMED_NAME_TEMPLATE" }` |
| `400` | Any other template variable has no value and no fallback | `{ "error": "Template variable(s) have no value...", "code": "TEMPLATE_VARIABLE_UNRESOLVED", "unresolvedVariables": ["line_email"] }` |
| `400` | `voiceNote: true` with no attachment | `{ "error": "voiceNote: true needs an audio attachment...", "code": "VOICE_NOTE_NO_ATTACHMENT" }` |
| `400` | `voiceNote: true` with a non-audio attachment | `{ "error": "voiceNote: true needs a direct link to an audio file...", "code": "VOICE_NOTE_NOT_AUDIO" }` |
| `400` | `fromLineId` is not a line in your workspace | `{ "error": "The specified line does not belong to this workspace.", "code": "LINE_NOT_FOUND" }` |
| `400` | More than 2 attachments | `{ "error": "Maximum 2 attachments per message" }` |
| `400` | Attachment URL belongs to another workspace | `{ "error": "Attachment URL does not belong to this organization" }` |
| `400` | Every attachment is unreachable and there is no text | `{ "error": "No attachment is sendable and the message text is empty...", "code": "ATTACHMENT_UNSENDABLE_NO_TEXT" }` |
| `400` | `recipientPhone` can't be dialled (bad NANP area/exchange code) | `{ "error": "That number can't receive messages (exchange code 019 cannot start with 0 or 1). Message not sent." }` |
| `400` | Bad `scheduledDate` or `sendWindowStart`/`sendWindowEnd` format | `{ "error": "Invalid scheduledDate format" }` |
| `400` | Send window start not earlier than end | `{ "error": "...", "code": "INVALID_SEND_WINDOW" }` |
| `400` | Timezone abbreviation or unknown timezone (with a send window) | `{ "error": "...", "code": "INVALID_TIMEZONE" }` |
| `400` | `allowedDaysOfWeek` not whole numbers 0–6 (with a send window) | `{ "error": "...", "code": "INVALID_ALLOWED_DAYS" }` |
| `401` | Invalid or missing API key | `{ "error": "Unauthorized" }` |
| `402` | Subscription past due (workspace read-only) | `{ "error": "READ_ONLY", "code": "READ_ONLY", "reason": "past_due" }` |
| `404` | `leadId` provided but not found | `{ "error": "Lead not found or access denied" }` |

***

## What happens after the API call

**1. Message created**

Tuco inserts a record in the `messages` collection with status `pending`
(or `scheduled` if `scheduledDate` is provided).

**2. Pre-send checks (worker)**

The worker checks line limits, time window, device gap, and contact gap.
If any fail, the message stays **queued** and is retried later — not failed.

**3. Availability check**

If the workspace has a line with Private API, Tuco checks whether the
recipient supports iMessage. If not → status becomes `fallback` and
fallback SMS fires (when configured).

> [!NOTE]
>
> `forceFallback: true` **skips this step entirely** — the message goes
> straight to the configured fallback channel and never runs an availability
> check (so it doesn't consume the availability-check budget or line cap).

**4. Send**

For individual messages: up to **5 send attempts** with delivery
verification between each (polling for up to 90 seconds).

**5. Outcome**

`sent` → appears in Unibox + webhook fires.
`failed` → error recorded + optional fallback SMS.
`delivered` → confirmed later via device callbacks.

***

## Lead resolution

When you send without a `leadId`, Tuco resolves the recipient automatically:

> [accordion] Lead found by phone/email
>
> If an existing lead in your workspace matches the `recipientPhone` or
> `recipientEmail`, the message is linked to that lead. Any `altPhone`/`altEmail`
> fields you pass will **update** the lead (merge, not overwrite).

> [accordion] New lead created (Quick Sends)
>
> If no matching lead exists, Tuco creates one under a list called **"Quick Sends"**
> (created automatically if it doesn't exist). Alt contact fields are stored on
> the new lead.

> [accordion] leadId provided
>
> The lead must exist in your workspace. The message is linked to it.
> `recipientPhone`/`recipientEmail` from the body override the lead's stored
> contact for this specific send.

***

## Alt contact fields

When you pass `altPhone1`–`altPhone3` or `altEmail1`–`altEmail3`, they are
stored on the **lead** (not the message). The worker uses them as fallback
addresses when the primary address fails the iMessage availability check.

**Priority order for `messageType: "imessage"`:**

```
phone → altPhone1 → altPhone2 → altPhone3 → email → altEmail1 → altEmail2 → altEmail3
```

> [!WARNING]
>
> Alt fields are **merged** onto the lead. If a lead already has `altPhone1` set
> and you send a new message without `altPhone1`, the existing value is preserved.
> Only explicitly provided fields are overwritten.

***

## Fallback SMS on failure

By default, when a message fails (technical error), no SMS fallback is sent.

To enable:

1. Configure Twilio on your workspace (`GET /api/workspace/fallback-config`).
2. Set `sendFallbackSmsOnFailed: true` in the request body (per-message) or
   on the workspace (applies to all messages).

> [!NOTE]
>
> Setting `sendFallbackSmsOnFailed: true` without a configured fallback is **not an error**.
> The request returns `201` and the iMessage send goes ahead as normal — there is simply no
> SMS to fall back to if it fails. Read
> [`GET /api/workspace/fallback-config`](https://docs.tuco.ai/api-reference/endpoint/fallback-config) to confirm
> a fallback is set up before you rely on it.

| Scenario | Fallback SMS fires? |
| - | - |
| Status = `fallback` (no iMessage), Twilio configured | **Yes** — always |
| Status = `failed`, `sendFallbackSmsOnFailed: true`, Twilio configured | **Yes** |
| Status = `failed`, `sendFallbackSmsOnFailed: false` (default) | **No** |
| Status = `failed`, flag is `true` but no fallback configured | **No** — the send is accepted, there is just nothing to fall back to |

> [!NOTE]
>
> Fallback SMS requires `recipientPhone` on the message. Email-only messages
> will not trigger fallback SMS.


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