SMS Message status changes occur throughout the lifespan of a message from creation, through sending, to delivery.
Learn how to send an SMS
POSTSend SMS
Sends an SMS message. This endpoint supports multiple different ways to send an SMS message with many fields that are mutually exclusive.
For the destination phone number either the to field or the contactId field must be provided. If a contactId is provided, the destination number will be looked up from their contact information.
For the source phone number either the from field or the numberSetId field must be provided. If the numberSetId field is used, a number will be chosen from the number set at random.
For the message body either the text field or the smsTemplateId field must be provided. If using a template, the extData field will be used for any template replacements. If a contact is specified, the provided extData will be used preferentially over the data in the contact when expanding the template.
If sending an MMS message, the mediaUrl property must be provided. In this case the body fields are optional.
Setting the deliveryStatusEnabled flag (default false) will result in a DLR callback.
Setting the messageStatusCallback will result in a POST of json data once the message is sent.
The metadata parameter will allow for passing key/value pairs. If provided, these values will be available on the sms log record as well as any callbacks that are configured for sms.
We recommend using number sets, contacts, and sms templates for API usage since these will result in fewer changes over time.
application/json
application/json
Bearer {Your Authentication Token}
Generated using the v4 Authentication endpoint.
{
"from": "+15554081234",
"text": "Hello World!!",
"to": "+12025551234",
"deliveryStatusEnabled": "true",
"messageStatusCallback": "https://test-callback-url.com",
"metadata": {
"leadId": "myLeadId",
"customId": "myCustomId"
}
}
Possible Success, Accepted and Error codes
| Error Code | Description |
| 2000 | Message blocked. Your message has been blocked from reaching the destination. |
| 2001 | Carrier violation. The carrier is filtering out your messages from being delivered. |
| 2002 | Unallocated. The destination phone number is not allocated to a mobile network. |
| 2003 | Invalid destination. The carrier is reporting the number as being unreachable. |
| 2004 | Unknown. The delivery receipt has returned a generic error message. |
| 2005 | Spam detected. The carrier has blocked/filtered this message as spam. |
| 2010 | Mobile Network error: Temporary disruption in service. |
| 2011 | Mobile Network error: Unable to route message. Please retry. |
| 2012 | Mobile Network error: Network congestion. Please retry. |
| 2013 | Mobile Network error: No response received from carrier. Please retry |
| 2050 | The service type (sms or mms) is not allowed. |
| 2051 | Message is NULL, contains invalid characters or exceeded lengh |
| 2052 | Message too long/large. |
| 2053 | Message not configured for DLR. |
| 2054 | There was an error with the shortened URL used. |
| 2055 | The Campaign Registry campaign error. Campaign may be inactive. |
| 2056 | Message send limit exceeded. |
| 2060 | Account not provisioned for short code messaging. |
| 2061 |
Mobile operator rejected short code. Reasons: not provisioned, campaign expired or not allowed.
|
| 2070 | The `to` or `from` number is blocked. |
| 2071 | The `from` number has been blocked/filtered by carrier. |
| 2072 | The `to` number is blocked/opted out from receiving messages. |
| 2073 | The `from` or `to` number is either invalid, inactive or not enabled for service type. |
| 2074 | Either the `to` or `from` is not enabled for toll-free messaging. |
| 2075 | Messaging not enabled for destination country. |
| 2076 | Messaging to an emergency number is forbidden. |
| 2077 | The `to` number unavailable. Message is stored and will be resent. |
| 2078 | Unverified toll-free number. |
| 2090 | Malformed message. Contact you system administrator. |
| Success | |
| Accepted |
Example of Accepted DLR Response
"root":
"messageSid": "61f17c60-b0b1-11ee-b30d-1f3c08ecc9fa"
"messageStatus": "Accepted"