Send a Message

Send an SMS or MMS to a single recipient.

Endpoint

POST /api/v1/messaging/message

Request body

Field	Type	Required	Description
`to`	string	Yes	Recipient phone number in E.164 format (e.g., `+18005551234`)
`from`	string	Yes	Sender phone number in E.164 format. Must be an active number assigned to your account.
`body`	string	Conditional	Message text, up to 640 characters. Required for SMS. Optional for MMS if `mediaUrl` is provided.
`mediaUrl`	string	No	Publicly accessible URL to a media file. When provided, the message is sent as MMS.
`idempotencyKey`	string	No	Unique key to prevent duplicate sends on retries. See Idempotency.

SMS example

curl -X POST https://platform.textingline.com/api/v1/messaging/message \
  -u "your_key_id:your_key_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+18005551234",
    "from": "+18005559876",
    "body": "Your verification code is 482910"
  }'

MMS example

curl -X POST https://platform.textingline.com/api/v1/messaging/message \
  -u "your_key_id:your_key_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+18005551234",
    "from": "+18005559876",
    "body": "Check out our new collection!",
    "mediaUrl": "https://example.com/images/promo.jpg"
  }'

Response

{
  "id": "msg_DsAdb4EBYBh3z25sBA1qnv",
  "direction": "outbound",
  "to": "+18005551234",
  "from": "+18005559876",
  "body": "Your verification code is 482910",
  "status": "sent",
  "sentAt": "2026-03-15T14:30:05.000Z",
  "createdAt": "2026-03-15T14:30:00.000Z"
}

Field	Description
`id`	Unique message identifier, prefixed with `msg_`
`direction`	Message direction: `outbound` or `inbound`
`status`	One of `sent`, `queued`, or `failed`
`errorType`	Error classification. Present only when `status` is `failed`. See values below.
`errorMessage`	Human-readable error description. Present only when `status` is `failed`.
`sentAt`	ISO 8601 timestamp of when the message was sent to the provider. Absent when status is `failed`.
`createdAt`	ISO 8601 timestamp of when the message was created

Failed responses

When the message is accepted but the provider cannot deliver it (e.g., the recipient has opted out), the API returns a 201 response with status: failed instead of an HTTP error. This allows you to distinguish between request-level errors (4xx/5xx) and delivery-level failures.

{
  "id": "msg_Hp2sABcDeFgHiJkLmNoPqR",
  "direction": "outbound",
  "to": "+18005551234",
  "from": "+18005559876",
  "body": "Your verification code is 482910",
  "status": "failed",
  "errorType": "opted_out",
  "errorMessage": "The recipient has opted out from receiving messages from this sender.",
  "createdAt": "2026-03-15T14:30:00.000Z"
}

Error types

`errorType`	Description
`unknown`	An unspecified error occurred during message processing
`platform_error`	An internal platform error prevented the message from being sent
`provider_error`	The upstream provider encountered an internal processing error
`invalid_destination`	The destination number is invalid, unreachable, or not mobile
`invalid_sender`	The sender identity is not valid or not authorized
`destination_blocked`	The destination number is blocked from receiving messages
`opted_out`	The recipient has opted out from receiving messages
`invalid_content`	The message content is invalid or exceeds allowed limits
`routing_error`	The message could not be routed to the destination
`geographic_restriction`	The message was blocked due to geographic restrictions
`service_restricted`	The requested service type is not supported for this destination

Credits

Each message consumes credits from your account balance:

SMS: 2 credits (1 message + 1 carrier lookup)
MMS: 2 SMS credits + 1 MMS credit

If your balance is insufficient, the request is rejected with error code 33023. Check your credit balance in the dashboard.

Common errors

Code	Description
`33004`	The `from` number is not assigned to your account
`33009`	The `from` number is not in an active state
`33016`	Message body contains unsupported characters
`33019`	Message violates compliance rules
`33023`	Insufficient credits

See Error Codes for the full reference.