Send a message
Send an SMS or MMS. The message is accepted asynchronously and returns
202 Accepted with the message resource; its status starts as queued
and moves to a terminal state (delivered, failed, or undelivered) as
carrier delivery receipts arrive.
The from number must be one your organization owns, and the recipient
must have opted in. If consent is missing, the call returns
453 CONSENT_REQUIRED. Sends are rate limited per organization; bursts
return 429 RATE_LIMITED with a Retry-After header. If a recent number
lookup classified the recipient as a fixed (landline) line, the send is
rejected with 422 LINE_TYPE_BLOCKED.
Requires the messages:send scope.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/messages" \ -H "Content-Type: application/json" \ -d '{ "from": "+15551112222", "to": "+15554443333", "text": "hello from agentmessage", "priority": "default", "tag": "order-7421" }'{
"success": true,
"data": {
"id": "8f3a2b1c-1c2d-4e5f-9a8b-0c1d2e3f4a5b",
"from": "+15551112222",
"to": "+15554443333",
"text": "hello from agentmessage",
"channel": "sms",
"priority": "default",
"status": "queued",
"tag": "order-7421",
"created_at": "2026-04-26T12:00:00Z"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164"
}
}
}{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "rate limited",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "CONSENT_REQUIRED",
"message": "consent required",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}