Skip to main content

​
Why Delivery Outcomes Matter

When you send messages at scale, not every attempt will succeed:
  • Some addresses are invalid or no longer in use.
  • Some recipients don’t support iMessage.
  • Some channels are temporarily unavailable.
Tuco is designed so that, from your point of view:
  • Every message ends up in a clear, stable outcome state.
  • You can safely build automations that respond to those states.
  • You do not need to understand the underlying retry or routing logic.
This page focuses purely on the outcomes you see and how to use them.

​
Message Statuses You Can Build On

Across the app, APIs, and webhooks, you’ll see a small set of message statuses:
  • queued
    • The message is planned, but not yet eligible to send.
    • Common reasons:
      • Waiting for allowed hours or days.
      • Waiting for free capacity on a line.
      • Waiting for a delay between campaign steps.
    • Use this to monitor future workload and expected sends.
  • pending / sending
    • The message is in the process of being sent.
    • Use this to distinguish “actively in flight” from “just planned”.
  • sent
    • Tuco successfully handed the message to the downstream channel (e.g. iMessage, SMS, email) according to that channel’s contract.
    • Use this to:
      • Trigger internal workflows (“message was sent”).
      • Update activity feeds or timelines.
  • delivered (where supported)
    • Tuco received a confirmation that the message reached the recipient’s device or mailbox.
    • Not all channels support this; when they do, Tuco surfaces it clearly.
    • Use this to:
      • Measure true delivery rates.
      • Trigger time‑based follow‑ups (“sent and delivered, now wait X days”).
  • failed
    • Tuco determined that this message cannot be sent.
    • Typical reasons include:
      • Permanently invalid address.
      • Hard rejection from the underlying channel.
      • Configuration that makes the send impossible.
    • Failed messages are not silently retried.
    • Use this to:
      • Flag data for cleanup.
      • Alert operators for high failure rates on a campaign or line.
  • fallback
    • The primary channel you wanted to use isn’t available for this recipient (for example, no iMessage‑capable address), or sending on that path is not safe.
    • Tuco:
      • Marks the message as fallback.
      • Emits a clear event (see /api-reference/message-webhooks).
    • Use this to:
      • Switch to SMS or email, if appropriate.
      • Tag leads as “not reachable on iMessage”.

​
What Tuco Does vs What You Decide

Tuco handles:
  • Running availability checks behind the scenes.
  • Respecting your time windows, day‑of‑week rules, and line limits.
  • Deciding when to treat an error as final vs something that can be retried internally.
You handle:
  • Business decisions when you see failed or fallback:
    • Whether to try another channel.
    • Whether to mark a lead as needing attention.
    • Whether to treat repeated failures as a sign to stop contacting a segment.
  • Data hygiene:
    • Cleaning invalid numbers or emails.
    • Updating lead records after repeated failures.
  • Customer experience:
    • Avoiding aggressive retries in your own systems.
    • Respecting consent and preferences when switching channels.
This separation lets you rely on Tuco’s guardrails while still owning your customer‑facing behavior.

​
Typical Failure & Fallback Scenarios

​
1. Invalid or Out‑of‑Date Contact Info

What happens:
  • You send to a phone or email that is no longer valid.
  • The underlying channel rejects the message.
  • Tuco marks the message as failed and surfaces a clear reason in the UI and/or API.
How to react:
  • Suppress or clean the offending address in your own systems.
  • Consider updating your import or validation flows to catch these earlier.
  • Watch for patterns (e.g. a particular list or source producing many invalid contacts).

​
2. Recipient Does Not Support iMessage

What happens:
  • Tuco determines that none of the stored addresses for a lead support iMessage.
  • The iMessage path is not used.
  • The message is marked as fallback, and a webhook event is emitted if configured.
How to react:
  • Route follow‑up via your preferred alternative:
    • SMS for time‑sensitive notifications.
    • Email for longer‑form communication.
  • Tag the lead in your CRM as “no iMessage” so future campaigns choose appropriate channels.
  • Use /features/check-availability to periodically refresh availability and keep this accurate.

​
3. Limits, Time Windows, and Gaps

What happens:
  • A message cannot be sent right now because:
    • Daily limits on a line have been reached.
    • You’re outside allowed hours or days.
    • Your pacing rules between contacts on a line are still in effect.
  • Tuco leaves the message as queued and checks again later.
How to react:
  • Treat Queued as “not attempted yet”, not as a failure.
  • If many messages stay queued for long periods:
    • Add capacity by configuring more lines.
    • Relax your timing windows, if consistent with your brand and compliance.
    • Re‑evaluate how many campaigns you run in parallel on the same lines.

​
4. Sustained Problems on a Channel or Line

What happens:
  • A line or channel experiences longer‑lasting issues.
  • Tuco protects recipients and your account by:
    • Reducing or pausing sends on that path.
    • Exposing more failed, queued, or fallback outcomes instead of forcing traffic through.
How to react:
  • Use campaign and line‑level stats to:
    • Spot unusually high failed or fallback rates.
    • Identify which lines or campaigns are affected.
  • Temporarily:
    • Shift traffic to healthier channels or lines.
    • Pause specific campaigns while you investigate.
You do not need to manage any recovery mechanics in Tuco itself—just respond to the visible outcomes.

​
Using Outcomes in Your Own Systems

You can consume delivery outcomes through:
  • The Tuco UI (for operational teams).
  • The API responses and list endpoints.
  • Message webhooks (see /api-reference/message-webhooks) for real‑time integration.
Common patterns teams implement:
  • CRM updates
    • Mark a contact as “Reached”, “Bounced”, or “Fallback to SMS” based on final status.
    • Record last successful contact date vs last attempt date.
  • Automated follow‑ups
    • Start a different sequence when a message fails.
    • Trigger a task for a human when a VIP contact hits repeated failures.
  • Health dashboards
    • Track ratios of sent / delivered / failed / fallback per campaign, line, or segment.
    • Alert internally when failures or fallbacks cross a threshold.
All of this can be done using only the public surfaces Tuco exposes—no need to depend on worker internals or implementation details.

​
Send SMS via GoHighLevel (GHL) as fallback

When you receive a message.fallback webhook (recipient has no iMessage), you can send the same content as SMS using GoHighLevel LeadConnector. This keeps the conversation in one place in GHL. Webhook payload you receive (relevant fields):
  • body.leadId, body.ghlContactId, body.ghlLocationId
  • body.message — for fallback the message object is in body.message; use body.message.message for the text, or body.data.reason for context.
  • For outbound fallback (you tried to send iMessage, it failed): body.message is the full message document; body.message.message is the text to send via SMS.
GHL API call (LeadConnector): 
POST https://services.leadconnectorhq.com/conversations/messages
Authorization: Bearer <your_ghl_api_token>
Version: 2021-07-28
Content-Type: application/json
Body (form or JSON per GHL docs):
FieldValue
locationIdbody.ghlLocationId from webhook
contactIdbody.ghlContactId from webhook
messageText to send (e.g. body.message.message or the original message text)
typeSMS
lastMessageDateCurrent time (e.g. Date.now())
Example (n8n / automation): when the Failed & Fallback webhook fires, read ghlContactId, ghlLocationId, and the message text from the webhook body, then POST to LeadConnector’s conversations/messages with type: "SMS". The conversation will appear in GHL as SMS.
Tuco can also send fallback SMS via Twilio automatically when you enable sendFallbackSmsOnFailed and configure Twilio in workspace settings. The GHL approach above is for teams who want fallback to go through GoHighLevel instead.

​
Best Practices

  • Focus on trends, not one‑offs
    • Individual failures are normal.
    • Spikes in failed or fallback rates are what deserve attention.
  • Use fallbacks thoughtfully
    • Treat fallback as a chance to choose the channel that best fits the moment.
    • Avoid automatically “spamming in every channel” after a single fallback event.
  • Keep data clean
    • Clean or suppress addresses that repeatedly fail.
    • Feed learnings back into your imports and validation rules.
  • Respect consent
    • Before reacting to a failure or fallback with another channel, ensure your consent and opt‑out rules allow it.
    • See /features/compliance-and-optouts for patterns.
Handled this way, Tuco’s outcomes give you clear, actionable signals without revealing how the underlying infrastructure works—and allow you to design robust, customer‑friendly journeys on top.