> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tofrom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending messages

> Learn how to send SMS and MMS messages through the API

## 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:

```javascript theme={null}
const message = await sendMessage({
  to: '+15551234567',
  body: 'Hello world!'
});
```

## Specifying a sender

By default, messages are sent from your configured messaging service number. You can specify a different sender number:

```javascript theme={null}
const message = await sendMessage({
  to: '+15551234567',
  from: '+15559876543',
  body: 'Hello from a specific number!'
});
```

<Note>
  The `from` number must be configured in your workspace and verified with your messaging provider.
</Note>

## Sending to multiple recipients

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

```javascript theme={null}
const recipients = ['+15551234567', '+15557654321', '+15555555555'];

const promises = recipients.map(to =>
  sendMessage({
    to,
    body: 'Broadcast message to multiple recipients'
  })
);

const results = await Promise.all(promises);
```

## 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)

<Warning>
  Carriers charge for each message segment. A 300-character message counts as 2 SMS messages.
</Warning>

## MMS messages

To send multimedia messages, include media URLs:

```javascript theme={null}
const message = await sendMessage({
  to: '+15551234567',
  body: 'Check out this image!',
  mediaUrl: 'https://example.com/image.jpg'
});
```

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:

| Status        | Description                              |
| ------------- | ---------------------------------------- |
| `queued`      | Message accepted and queued for delivery |
| `sending`     | Message is being sent to carrier         |
| `sent`        | Message sent to carrier network          |
| `delivered`   | Message confirmed delivered to device    |
| `failed`      | Message could not be delivered           |
| `undelivered` | Message sent but not delivered           |

## Error handling

Always implement proper error handling:

```javascript theme={null}
try {
  const message = await sendMessage({
    to: '+15551234567',
    body: 'Hello world!'
  });
  console.log('Message sent:', message.sid);
} catch (error) {
  if (error.status === 400) {
    console.error('Invalid request:', error.message);
  } else if (error.status === 401) {
    console.error('Authentication failed');
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## 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

```javascript theme={null}
async function sendReminder(phoneNumber, appointmentTime) {
  return await sendMessage({
    to: phoneNumber,
    body: `Reminder: Your appointment is scheduled for ${appointmentTime}. Reply CONFIRM to confirm or CANCEL to cancel.`
  });
}
```

### Send a verification code

```javascript theme={null}
async function sendVerificationCode(phoneNumber, code) {
  return await sendMessage({
    to: phoneNumber,
    body: `Your verification code is: ${code}. This code expires in 10 minutes.`
  });
}
```

### Send a marketing message

```javascript theme={null}
async function sendPromotion(phoneNumber, promoCode) {
  return await sendMessage({
    to: phoneNumber,
    body: `🎉 Special offer! Use code ${promoCode} for 20% off your next order. Reply STOP to unsubscribe.`
  });
}
```

## Next steps

* [Track message delivery status](/guides/message-status)
* [Handle inbound messages](/guides/receiving-messages)
* [Set up error handling](/guides/error-handling)