Skip to main content
POST
/
api
/
messages
/
cancel-for-lead
Cancel Pending Messages
curl --request POST \
  --url https://app.tuco.ai/api/messages/cancel-for-lead \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "leadId": "<string>",
  "recipientPhone": "<string>",
  "recipientEmail": "<string>"
}
'
{
  "success": true,
  "cancelledCount": 123,
  "jobsRemovedFromQueue": 123,
  "leadId": "<string>",
  "messageIds": [
    "<string>"
  ]
}
Call this endpoint when a lead replies “Stop”, “Unsubscribe”, or any opt-out keyword. It cancels all pending, scheduled, and queued messages for that lead and removes their jobs from the processing queue.

​
Authentication

Authorization: Bearer tuco_sk_xxxxxxxxxxxxx

​
Request body

You must provide at least one of these identifiers:
​
leadId
string
Cancel all pending messages for this lead ID. Most direct — skips the lookup step.
​
recipientPhone
string
Phone number (E.164 format). Tuco looks up the lead by phone (including altPhone1-3), then cancels all pending messages for that lead. If no lead is found, cancels messages matching this phone directly.
​
recipientEmail
string
Email address. Tuco looks up the lead by email (including altEmail1-3), then cancels all pending messages for that lead. If no lead is found, cancels messages matching this email directly.

​
How it works

1

Identify the lead

If leadId is provided, use it directly. Otherwise, look up the lead by recipientPhone or recipientEmail (checks primary + alt fields).
2

Find cancellable messages

Query all messages for this lead (or address) with status queued, pending, or scheduled.
3

Cancel in database

Bulk update all matching messages to status: "cancelled".
4

Remove from queue

Remove each message’s BullMQ processing job so it won’t be picked up by the worker.

​
Examples

curl -X POST "https://app.tuco.ai/api/messages/cancel-for-lead" \
  -H "Authorization: Bearer tuco_sk_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "recipientPhone": "+14422646782" }'

​
Success response (200)

{
  "success": true,
  "cancelledCount": 3,
  "jobsRemovedFromQueue": 2,
  "leadId": "69b2c41d352a78479d2c623b",
  "messageIds": [
    "69dba0001111111111111111",
    "69dba0001111111111111112",
    "69dba0001111111111111113"
  ]
}
​
success
boolean
Always true on success (even when 0 messages cancelled).
​
cancelledCount
integer
Number of messages set to cancelled in the database.
​
jobsRemovedFromQueue
integer
Number of BullMQ jobs removed. May be less than cancelledCount if some jobs already started processing.
​
leadId
string
The resolved lead ID (may be null if no lead was found and cancellation was done by address).
​
messageIds
string[]
IDs of all cancelled messages.

​
Error responses

StatusWhenBody
400No identifier provided{ "error": "Either leadId, recipientPhone, or recipientEmail is required" }
400Invalid leadId format{ "error": "Invalid leadId" }
401Missing or invalid API key{ "error": "Unauthorized" }
500Server error{ "error": "Internal server error" }

​
Usage with n8n / automation

Wire this into your reply handler workflow. When a lead replies with an opt-out keyword, call this endpoint with their phone number to stop all future sequence messages: 
{
  "method": "POST",
  "url": "https://app.tuco.ai/api/messages/cancel-for-lead",
  "headers": { "Authorization": "Bearer tuco_sk_xxxxxxxxxxxxx" },
  "body": { "recipientPhone": "{{ $json.phone }}" }
}