Twilio

Send SMS and MMS messages to your customers via the Twilio Programmable Messaging API. Zeotap sends one message per row in your sync, with support for dynamic message templates powered by your warehouse data.

Prerequisites

• A Twilio account with Programmable Messaging enabled
• Your Twilio Account SID and Auth Token (found in the Twilio Console)
• A Twilio phone number or Messaging Service SID capable of sending SMS/MMS

Permissions

Your Twilio account must have:

• An active, non-suspended status
• At least one phone number or Messaging Service provisioned for SMS
• Sufficient account balance or auto-recharge enabled for message delivery

Authentication

Twilio uses Account SID + Auth Token authentication (HTTP Basic Auth).

1. Log in to the Twilio Console
2. On the dashboard, locate your Account SID (starts with AC)
3. Click the eye icon next to Auth Token to reveal and copy it
4. In Zeotap, paste the Account SID and Auth Token into the corresponding fields

Configuration

Twilio does not require additional configuration fields beyond authentication.

Target Settings

Supported Operations

Sync Modes

Twilio is an append-only messaging API. Each sync run sends a new message for every row. There is no concept of updating or deleting a previously sent message.

Audience Sync Modes

Twilio does not support audience sync modes. There is no list or segment membership API in the Twilio Programmable Messaging product.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

to, body, media_url, status_callback

How It Works

1. Zeotap reads rows from your configured model or audience
2. For each row, the Message Template is rendered by replacing {{field_name}} placeholders with values from the row
3. A POST request is sent to https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json with form-encoded parameters: To, From, and Body
4. If a media_url field is mapped, it is included as MediaUrl to send an MMS
5. If a status_callback field is mapped, it is included as StatusCallback for delivery status webhooks
6. Messages are sent one at a time per row (Twilio does not offer a batch send endpoint)
7. Failed messages are retried up to 3 times with exponential backoff; 429 Too Many Requests and 5xx errors trigger automatic retries

Batch Size

Messages are sent individually (1 per API call). Zeotap processes rows sequentially within each batch to respect Twilio account-level rate limits.

Error Handling

• Invalid phone number: Twilio returns a 400 error with a descriptive message; the row is marked as failed
• Rate limiting (429): The writer automatically retries with exponential backoff, respecting Retry-After headers
• Server errors (5xx): Retried up to 3 times before marking the row as failed
• Authentication failure (401): All remaining rows in the batch fail immediately

Rate Limits

Twilio enforces account-level concurrency limits on API requests. During high-volume sends:

• You may receive 429 Too Many Requests responses, which Zeotap handles automatically with retries
• Monitor your Twilio Console for the Twilio-Concurrent-Requests header to understand current utilization
• For high-throughput use cases, consider upgrading your Twilio account or using a Messaging Service with rate limiting built in

The default SMS throughput for US long codes is 1 message per second. Toll-free numbers support up to 25 messages per second. Short codes support 100+ messages per second, depending on your carrier approval.

Best Practices

• Use E.164 format for all phone numbers (e.g. +15551234567) to ensure reliable delivery
• Keep messages concise — SMS messages over 160 GSM-7 characters (or 70 UCS-2 characters) are split into multiple segments, each billed separately
• Use a Messaging Service instead of a raw phone number for the From field to benefit from automatic sender selection, opt-out handling, and compliance features
• Test with a small audience first before sending to large segments to validate your message template
• Map status_callback to a URL if you need delivery receipts for tracking message status
• Monitor your Twilio balance — messages fail if your account runs out of funds

Troubleshooting

Authentication failed: invalid Account SID or Auth Token

Verify your credentials in the Twilio Console. The Account SID starts with AC and is 34 characters long. The Auth Token is a 32-character hex string. If you recently rotated your Auth Token, update it in Zeotap.

Message not delivered: invalid To number

Ensure the recipient phone number is in E.164 format (e.g. +15551234567). The number must include the country code prefix. Twilio rejects numbers without a valid country code.

Error 21211: Invalid ‘To’ Phone Number

This Twilio error means the destination number is not a valid phone number. Check that your source column contains properly formatted phone numbers, not names or email addresses.

Error 21608: The number is unverified

In Twilio trial accounts, you can only send messages to verified phone numbers. Upgrade to a paid account or verify the recipient number in the Twilio Console under Verified Caller IDs.

Messages are being sent slowly

Zeotap sends messages sequentially to respect Twilio rate limits. For higher throughput, consider using a Twilio Messaging Service with a pool of numbers, or upgrading to short codes or toll-free numbers which support higher send rates.

Error 30003: Unreachable destination handset

The recipient’s phone is turned off, out of coverage, or has blocked SMS. This is a carrier-level issue. Twilio will report the delivery failure. Consider implementing retry logic in your sync schedule for transient delivery failures.

MMS not sending: missing MediaUrl

To send MMS messages, map a media_url field containing a publicly accessible URL to the media file. The URL must be reachable by Twilio’s servers. Supported formats include JPEG, PNG, and GIF (up to 5 MB).

Error 20003: Authentication required

Your Twilio account may be suspended or the credentials may have been invalidated. Log in to the Twilio Console to check your account status and regenerate your Auth Token if needed.