Send Messages - Tuco AI

Overview

Send iMessage, SMS, or email to leads or arbitrary recipients. Messages can be sent immediately or scheduled for later delivery.

Quick Send

Send one-off messages without creating leads

Send to Leads

Campaign messages and bulk outreach

Quick Send

Perfect for testing, one-off messages, or contacting people not in your system.

No lead required - Send directly to any phone or email address

How to Quick Send

Open Quick Send

Navigate to Leads → Import and click Quick Send button

Enter Recipient

Type recipient address:

Phone: Include country code (e.g., +12025551234)
Email: Full email address

Check Availability

System automatically checks iMessage availability:

🔵 Blue icon - iMessage available
⚪ Gray icon - Will send as SMS/email

Compose Message

Type your message in the text area

Choose Timing

Select delivery time:

Send Now - Immediate delivery
Send Later - Schedule for specific date/time

Send

Click Send Now or Schedule Message

Limitations

Cannot send to unavailable addresses (button will be disabled)
Must have an active line configured
Message length limits apply based on type

Send to Leads

The recommended method for campaigns, follow-ups, and organized outreach.

Single Lead Message

Send to one lead at a time:

Navigate to Leads page
Find and select a lead (checkbox)
Click Send Message in toolbar
Compose and configure message
Click Send

Bulk Messaging

Send to multiple leads simultaneously:

Select Leads

Check multiple leads in the table

Open Message Composer

Click Send Message (bulk action)

Compose Message

Type your message (same for all recipients)

Choose Message Type

System automatically selects optimal type:

iMessage - If available
SMS - Fallback for unavailable iMessage
Email - Email delivery

Set Timing

Choose immediate or scheduled delivery

Send Batch

Click Send - progress indicator shows completion

Batch Processing: Messages are sent sequentially with individual delivery status per lead.

Message Types

Choose the right message type for your communication:

iMessage

Blue bubbleApple iMessage deliveryRequires: iMessage enabled

SMS

Green bubbleStandard text messageRequires: Any mobile number

Email

Email deliveryEmail client deliveryRequires: Valid email address

The system automatically selects the best delivery method based on availability checks.

Scheduling Messages

Send messages at the perfect time, even when you’re not available.

Schedule for Later

Select 'Send Later'

Choose the scheduling option when composing

Pick Date

Use calendar picker to select date

Pick Time

Use time picker for specific hour/minute

Validation

System validates:

Must be future date/time
Cannot be in the past

Queue Message

Message saved with Scheduled status

How Scheduled Messages Work

Processing: Scheduled messages are processed by a cron job that runs every minute.

Managing Scheduled Messages

View and manage your scheduled messages:

Navigate to Messages page
Filter by status: Scheduled
Can cancel messages before send time
Edit or reschedule as needed

Message Tracking

Every message includes comprehensive tracking data:

Message Properties

string

Current message state:

Sent - Successfully delivered
Scheduled - Queued for future send
Failed - Delivery failed
Cancelled - Manually cancelled

datetime

When message was sent or scheduled

object

Lead reference or direct address

string

Which line sent the message

string

iMessage, SMS, or Email

string

For bulk sends - links related messages

View Message History

Access complete message logs:

Navigate to Messages page
Use filters:
- Status
- Date range
- Message type
- Recipient
Search by content or recipient name
Export for analysis

API Reference

Send messages programmatically via REST API.

Send Message Endpoint

POST /api/messages

Headers:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <clerk_token>"
}

Request Body:

{
  "message": "Hello! This is a test message.",
  "messageType": "imessage",
  "fromLineId": "507f1f77bcf86cd799439011",
  "recipientPhone": "+12025551234",
  "recipientName": "John Doe",
  "scheduledDate": "2025-10-15T14:30:00Z",
  "leadId": "507f1f77bcf86cd799439012"
}

Request Parameters

string

required

Message text content

string

required

One of: imessage, sms, or email

string

required

ID of the line to send from

string

Phone number (required if no recipientEmail)

string

Email address (required if no recipientPhone)

string

Display name for recipient

datetime

ISO 8601 timestamp for scheduled delivery

string

Associated lead ID (optional)

string

Batch identifier for bulk operations

Response:

{
  "success": true,
  "message": {
    "_id": "507f1f77bcf86cd799439013",
    "message": "Hello! This is a test message.",
    "messageType": "imessage",
    "status": "sent",
    "createdAt": "2025-10-14T10:30:00Z"
  }
}

Error Codes

Code	Description
`400`	Missing required fields or invalid data
`401`	Unauthorized - invalid or missing token
`404`	Lead or line not found
`500`	Server error - delivery failed

Complete API Docs

View detailed API documentation with more examples

Best Practices

✅ Do’s

Check Availability First

Always verify iMessage availability before bulk sending to maximize delivery rates

Use Scheduling Wisely

Schedule messages for optimal times based on your audience’s timezone and habits

Personalize Messages

Use lead data to personalize messages and increase engagement

Test First

Use Quick Send to test messages before launching full campaigns

Monitor Delivery

Regularly check delivery status and adjust strategy based on results

❌ Don’ts

Avoid these common mistakes:

❌ Sending to unchecked addresses
❌ Spamming recipients with multiple messages
❌ Sending without an active line configured
❌ Using all caps or excessive punctuation
❌ Sending promotional content without consent
❌ Ignoring delivery failures and errors

Troubleshooting

Message Failed to Send

Common causes:

Recipient address is invalid
Line is not active or misconfigured
Server connection issue

Solution: Verify recipient address, check line status, and retry

Scheduled Message Didn't Send

Common causes:

Line became inactive
Server was down at scheduled time
Message was cancelled

Solution: Check message status in Messages page, verify line is active

Cannot Send to Unavailable Address

Cause: Recipient doesn’t support iMessage and message type is set to iMessage onlySolution: Change message type to SMS or Email, or use auto-select mode

​Overview

Quick Send

Send to Leads

​Quick Send

​How to Quick Send

​Limitations

​Send to Leads

​Single Lead Message

​Bulk Messaging

​Message Types

iMessage

SMS

Email

​Scheduling Messages

​Schedule for Later

​How Scheduled Messages Work

​Managing Scheduled Messages

​Message Tracking

​Message Properties

​View Message History

​API Reference

​Send Message Endpoint

​Request Parameters

​Error Codes

Complete API Docs

​Best Practices

​✅ Do’s

​❌ Don’ts

​Troubleshooting

Overview

Quick Send

How to Quick Send

Limitations

Send to Leads

Single Lead Message

Bulk Messaging

Message Types

Scheduling Messages

Schedule for Later

How Scheduled Messages Work

Managing Scheduled Messages

Message Tracking

Message Properties

View Message History

API Reference

Send Message Endpoint

Request Parameters

Error Codes

Best Practices

✅ Do’s

❌ Don’ts

Troubleshooting