Skip to main content

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.

​
Overview

Verify whether a lead’s phone number or email supports iMessage before sending messages. The system automatically checks all new leads and provides manual re-check options.
iMessage availability checking helps you send messages through the optimal channel and avoid delivery failures.

​
Automatic Checking

When you upload leads, the system automatically checks availability:
1

Upload Detection

System detects new leads from upload
2

Address Check

Automatically checks all phone and email addresses
3

Status Update

Updates lead record with availability status

​
Status Indicators

IconStatusDescription
🔵AvailableSupports iMessage (blue bubble)
⚪UnavailableDoes not support iMessage (SMS/email only)
🔄CheckingCurrently verifying
⚠️ErrorCheck failed - retry available
⭕No Active LineConfigure a line first

​
Manual Checking

​
Single Lead Check

Check availability for individual leads:
  1. Navigate to Leads page
  2. Find the lead in the table
  3. Click Check Availability button
  4. Status updates in real-time
Re-check leads periodically as contacts may enable or disable iMessage on their devices.

​
Bulk Checking

Check multiple leads at once:
  1. Select multiple leads using checkboxes
  2. Click Check Availability (bulk action in toolbar)
  3. System checks all selected leads
  4. Progress indicator shows completion
Bulk checking is processed sequentially. Large batches may take a few minutes. Each line can perform up to 70 availability checks per day. If you have multiple lines, checks are distributed across them automatically. High-volume checks may experience slight delays.

​
Quick Send Preview

Get instant availability feedback when composing quick messages:
1

Open Quick Send

Navigate to Leads → Import and click Quick Send
2

Enter Recipient

Type phone number or email address
3

Auto-Check

System automatically checks availability (500ms debounce)
4

View Status

See availability icon next to recipient field

​
Status Icons

  • 🔵 Blue circle - iMessage available
  • ⚪ Gray circle - Not available (will send as SMS/email)
  • ⏳ Spinner - Checking…

​
How It Works

Understanding the availability check process:

​
Check Priority

The system checks addresses in this order and stops at the first available one:
  1. Primary phone
  2. Primary email
  3. Alternate phone 1
  4. Alternate phone 2
  5. Alternate phone 3
  6. Alternate email 1
  7. Alternate email 2
  8. Alternate email 3
Checking stops at the first available address to optimize performance.

​
Requirements

Before checking availability, you must have an active line configured:
Important: Without an active line, all checks will show “No Active Line” status.

​
Setup Required

  1. Navigate to Lines page
  2. Purchase or configure a line
  3. Ensure line status is Active
  4. Line must have a valid Server URL

Configure Lines

Learn how to set up and manage your messaging lines

​
API Reference

​
Check Single Lead

Check availability for a specific lead by ID. 
GET /api/leads/check-availability?id={leadId}
Response: 
{
  "success": true,
  "leadId": "507f1f77bcf86cd799439011",
  "available": true,
  "status": "available"
}

​
Check Multiple Leads

Batch check multiple leads at once. 
POST /api/leads/check-availability
Request: 
{
  "leadIds": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012",
    "507f1f77bcf86cd799439013"
  ]
}
Response: 
{
  "success": true,
  "checked": 3,
  "successful": 3,
  "errors": 0,
  "results": [
    {
      "leadId": "507f1f77bcf86cd799439011",
      "available": true,
      "status": "available"
    },
    {
      "leadId": "507f1f77bcf86cd799439012",
      "available": false,
      "status": "unavailable"
    },
    {
      "leadId": "507f1f77bcf86cd799439013",
      "available": true,
      "status": "available"
    }
  ]
}

​
Check Individual Address

Check availability for a phone or email address (Quick Send). 
POST /api/leads/check-availability
Request: 
{
  "address": "+12025551234"
}
Response: 
{
  "success": true,
  "available": true,
  "address": "+12025551234"
}

​
Error Codes

CodeDescription
400No active line configured
401Unauthorized - invalid or missing token
404Lead not found
500Server error - check failed

​
API Integrators: Skip Checking, Use Fallback Webhooks

If you’re integrating via API (not using the Tuco UI), the recommended pattern is to skip availability checking entirely:
  1. Call POST /api/messages directly
  2. Listen for the message.fallback webhook
  3. When you receive message.fallback, trigger your SMS/WhatsApp fallback
This avoids burning your 70/day/line availability quota and is faster (one API call instead of two). See the check-availability-rr endpoint for code examples.

​
Availability Checks vs Send Limits

Availability checks and message sends use separate daily counters. Checking a number does not reduce your daily send quota, and sending a message does not reduce your availability check quota.
CounterScopeLimit
Send quotaPer line, per dayConfigured per line (see Lines page)
Availability quotaPer line, per day70 checks/day (hard cap)

​
Best Practices

Re-check leads periodically (weekly/monthly) as people change devices and enable/disable iMessage
Use bulk checking for large lists to save time and ensure all leads are current
Always verify availability before launching messaging campaigns to maximize deliverability
If you see high error rates, verify your line configuration and server URL

​
Troubleshooting

Solution: Configure an active line in Settings → Lines before checking availability.
Solution: Verify your server URL is correct and accessible. Check network connectivity.
Solution: Refresh the page. If issue persists, check your line’s server status.