Skip to main content

​
Overview

Sends an SMS text message to a phone number using one of your Magpipe numbers as the sender.

​
Request

​
Headers

​
Authorization
string
required
Bearer token for authentication.
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
to
string
required
Recipient phone number in E.164 format.Example: "+14155551234"Constraints:
  • Must start with + followed by country code
  • 10-15 digits total
​
from
string
required
Your Magpipe phone number to send from. Must be SMS-enabled.Example: "+16045551234"
​
body
string
required
The message content.Example: "Your appointment is confirmed for tomorrow at 2pm."Constraints:
  • Maximum 1600 characters
  • Messages over 160 characters are sent as multiple segments
​
media_urls
array
Array of URLs for MMS media attachments.Example: ["https://example.com/image.jpg"]Constraints:
  • Maximum 10 media items
  • Supported formats: jpg, png, gif, pdf
  • Maximum 5MB per file
​
scheduled_at
string
ISO 8601 timestamp to schedule the message for later delivery.Example: "2024-01-16T10:00:00Z"Constraints:
  • Must be in the future
  • Maximum 7 days ahead

​
Response

​
success
boolean
Whether the message was sent/queued successfully.
​
message_id
string
Unique identifier for the message.
​
status
string
Current message status:
  • queued - Message is queued for delivery
  • sent - Message sent to carrier
  • scheduled - Message scheduled for future delivery
​
segments
integer
Number of SMS segments the message was split into.
​
created_at
string
ISO 8601 timestamp.

​
Example Request

curl -X POST "https://mtxbiyilvgwhbdptysex.supabase.co/functions/v1/send-sms" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "from": "+16045551234",
    "body": "Your appointment is confirmed for tomorrow at 2pm. Reply YES to confirm or NO to reschedule."
  }'

​
Example Response

{
  "success": true,
  "message_id": "msg_a1b2c3d4-5678-9012-3456-789012345678",
  "status": "sent",
  "segments": 1,
  "from_number": "+16045551234",
  "to_number": "+14155551234",
  "created_at": "2024-01-15T10:30:00.000Z"
}

​
Error Responses

{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "The 'to' field must be a valid E.164 phone number"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired access token"
  }
}

{
  "error": {
    "code": "SMS_NOT_ENABLED",
    "message": "The 'from' number does not have SMS capability"
  }
}

​
Message Status Webhook

When the message status changes, a webhook is sent to your configured URL: 
{
  "event": "message.status_changed",
  "message_id": "msg_a1b2c3d4-5678-9012-3456-789012345678",
  "status": "delivered",
  "to_number": "+14155551234",
  "from_number": "+16045551234",
  "timestamp": "2024-01-15T10:30:05.000Z"
}

​
Message Status Values

StatusDescription
queuedMessage queued for sending
sentMessage sent to carrier
deliveredConfirmed delivered to recipient
undeliveredCould not be delivered
failedFailed to send

​
SMS Segment Calculation

SMS messages are split into segments:
Character SetCharacters per Segment
GSM-7 (standard)160 characters
Unicode (emojis, etc.)70 characters
Messages split across multiple segments include headers, reducing usable characters to 153 (GSM-7) or 67 (Unicode) per segment.