Skip to main content
POST
/
v1
/
sms
cURL
curl --request POST \
  --url https://api.buildwithchirp.com/v1/sms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": "+15551234567",
  "to": [
    "+15559876543"
  ],
  "text": "Hello from Chirp!",
  "subject": "Important Message",
  "mediaUrls": [
    "https://example.com/image.jpg"
  ],
  "transport": "automatic"
}
'
{
  "id": "msg_sms_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "from": "<string>",
  "to": [
    "<string>"
  ],
  "text": "<string>",
  "subject": "<string>",
  "direction": "OUTBOUND",
  "createdAt": "<string>",
  "mediaUrls": [
    "<string>"
  ]
}

Authorizations

​
Authorization
string
header
required

App API key (format: sk_live_app_* or sk_test_app_*) for app-level operations

Body

application/json
​
from
string
required

Phone number to send from (must be assigned to your app). E.164 format required.

Example:

"+15551234567"

​
to
string[]
required

Array of phone numbers to send to. E.164 format required.

Example:
["+15559876543"]
​
text
string

Message text content

Example:

"Hello from Chirp!"

​
subject
string

Subject for MMS messages

Example:

"Important Message"

​
mediaUrls
string<uri>[]

Array of media URLs for MMS messages

Example:
["https://example.com/image.jpg"]
​
transport
enum<string>
default:automatic

Transport method: 'automatic' (decide based on content), 'sms' (force SMS), or 'mms' (force MMS)

Available options:
automatic,
sms,
mms
Example:

"automatic"

Response

Message queued successfully

​
id
string
required

Unique identifier for a Message. Format: msg_sms_[test_]{ksuid}

Pattern: ^msg_sms_(?:test_)?[a-zA-Z0-9]{27}$
Example:

"msg_sms_2DbBs7GWhGvVNJGrDXr5RG0mBWI"

​
from
string
required
​
to
string[]
required
​
text
string | null
required
​
subject
string | null
required
​
type
enum<string>
required
Available options:
SMS,
MMS
​
transport
enum<string>
required
Available options:
sms,
mms
​
direction
enum<string>
required
Available options:
OUTBOUND
​
status
enum<string>
required
Available options:
QUEUED,
SENDING,
SENT,
DELIVERED,
FAILED
​
createdAt
string
required
​
mediaUrls
string[]