Skip to main content

Overview

Our messaging API allows you to send both SMS (text) and MMS (multimedia) messages programmatically. Messages are queued and delivered through your configured messaging provider.

Basic SMS message

The simplest way to send a message requires just two parameters:

Specifying a sender

By default, messages are sent from your configured messaging service number. You can specify a different sender number:
The from number must be configured in your workspace and verified with your messaging provider.

Sending to multiple recipients

To send messages to multiple recipients, make parallel API calls:

Long messages

SMS messages longer than 160 characters are automatically split into multiple segments:
  • Single SMS: Up to 160 characters
  • Multi-part SMS: Up to 1,600 characters (split into segments of 153 characters each)
Carriers charge for each message segment. A 300-character message counts as 2 SMS messages.

MMS messages

To send multimedia messages, include media URLs:
Supported media types:
  • Images: JPEG, PNG, GIF (up to 5MB)
  • Audio: MP3, WAV (up to 5MB)
  • Video: MP4, 3GP (up to 5MB)
  • Documents: PDF, VCF (up to 5MB)

Message status

All messages start with a queued status and progress through these states:

Error handling

Always implement proper error handling:

Best practices

  1. Validate phone numbers: Always validate and format phone numbers in E.164 format (+country code + number)
  2. Handle rate limits: Implement exponential backoff for rate limit errors
  3. Log message SIDs: Store the message SID for tracking and debugging
  4. Use callbacks: Set up webhooks to receive real-time delivery updates
  5. Test thoroughly: Test with different carriers and number types

Examples

Send a reminder

Send a verification code

Send a marketing message

Next steps