post

/messaging

authorization: basic

Send a message (with a verification code if you wish), specify the type of message, what phase of the account lifecycle the message is being sent in, and additional details about the transaction. NOTE: If you try this API out using the API Explorer, you will be billed for the transaction as you normally would.

  • Can be authenticated with Basic (easiest to implement) and Digest
  • Use https://rest-ww.telesign.com/v1/messaging as the base endpoint
  • Accept only UTF-8 encoded unicode characters as inputs
  • Use Content-Type - application/x-www-form-urlencoded in request headers

Request Body

Schema
object
phone_number
string

The end user’s phone number with country code included. Avoid use of special characters and spaces.

required
message
string

Text of the message to be sent to the end user. You are limited to 1600 characters. If you send a very long message, TeleSign splits your message into separate parts. TeleSign recommends against sending messages that require multiple SMSes when possible.

required
message_type
string

This parameter specifies the traffic type being sent in the message. You can provide one of the following values -

  • OTP (One time passwords)
  • ARN (Alerts, reminders, and notifications)
  • MKT (Marketing traffic)
required
account_lifecycle_event
string

This parameter allows you to indicate what phase of the lifecycle you are in when you send a transaction. The options for this parameter are -

  • create - For the creation of a new account)
  • sign-in For when an end user signs in to their account.
  • transact - For when an end user completes a transaction within their account
  • update - For when an update is performed, such as an update of account information or similar.
  • delete - For when an account is deleted.
sender_id
string

This parameter allows you to set a specific sender ID to be used on an SMS message sent to the end user. In order to use a specific sender ID, TeleSign must whitelist your selected sender ID values. Be aware that 100% preservation of a sender ID value is not guaranteed. TeleSign may override the sender ID value that your end user will receive in order to improve delivery quality or follow SMS regulations in particular countries. In order to use this feature, you must contact TeleSign Support and have them enable it for you.

originating_ip
string

Your end user’s IP address (do not send your own IP address). This value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Textual Representation of IPv4 and IPv6 Addresses.

Responses

Your request was fulfilled and resulted in a new resource being created. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.

Status Code Associated Text String Description
200 Delivered to handset The SMS was delivered to the end user’s phone. (Final)
203 Delivered to gateway The SMS was delivered to the gateway. If the gateway responds with further information (including successful delivery to handset or delivery failure), the status is updated. (Intermediate)
207 Error delivering SMS to handset (reason unknown) The SMS could not be delivered to the end user’s handset for an unknown reason. (Final)
210 Temporary phone error The SMS could not be delivered to the handset due to a temporary error with the phone. Examples - phone is turned off, not enough memory to store the message. (Final)
211 Permanent phone error The SMS could not be delivered to the handset due to a permanent error with the phone. For example, the phone is incompatible with SMS, or illegally registered on the network. This can happen when a phone number is blacklisted, or is incorrectly provisioned. (Final)
220 Gateway/network cannot route message The network cannot route the message to the handset. (Final)
221 Message expired before delivery The message was queued by the mobile provider and timed out before it could be delivered tothe handset. (Final)
222 SMS not supported SMS is not supported by this phone, carrier, plan, or user.
229 Message blocked by your request TeleSign blocked the SMS before it was sent. This is due to your prior submitted request to blocklist this phone number.
230 Message blocked by TeleSign TeleSign blocks a message if it is being sent to a phone number that is on a global blocklist.
231 Invalid/unsupported The content of the message is not supported.
237 Message blocked in requested country You requested that messages in a specific country be blocked, and the message was being sent to this country.
238 Destination blocked by prefix You requested that phone numbers with a particular prefix be blocked.
250 Final status unknown The final status of the SMS cannot be determined.
286 Transaction not attempted The SMS is blocked from being sent due to the phone type not being one of the following - mobile, prepaid, personal, or pager.
290 Message in progress The message is being sent to the SMS gateway.
292 Queued by gateway The SMS gateway has queued the message.
295 Status delayed The status of the SMS is temporarily unavailable.
500 Transaction not attempted No SMS request was attempted.
502 Campaign error This error can be generated if there is a problem with the short code used.
503 Carrier rejected - temporary problem This error is generated if there is an error on the carrier or operator side that is temporary and the message can be retried.
504 Carrier rejected - permanent error This error is generated if there is an error on the carrier or operator side that is permanent and the message should not be retried.
505 Error on gateway - temporary error This error is generated if there is an error on TeleSign’s partner side that is considered temporary and the message can be retried.
506 Error on gateway - permanent error This error is generated if there is an error on TeleSign’s partner side that is considered permanent and the message should not be retried.
507 Invalid destination address There is a problem with the destination address used. Either the format is not valid, or the number is not associated with any carrier, or if MSC is used it does not know about this MSISDN.
508 Invalid source address The message requires a source address. Verify that one is provided and correct.
510 Message blocked by subscriber action or request The end user has blocked receiving SMS with their carrier plan or by request or from the particular short code used.
511 Subscriber low on credit The end user exceeded their spending limits and cannot receive SMS.
512 Roaming error End user cannot receive SMS because their device that receives the messages is roaming.
513 Mobile number portability error SMS failed because ported combinations are unreachable.
514 Subscriber absent Subscriber is absent for a period of time.
515 Suspected spam This message is considered to be spam by carrier or operator.
599 Status not available The system is unable to provide status at this time.
Schema
object
reference_id
string

A 32-digit hex value used to identify the web service request. The value is unique to each web service request, is randomly generated by TeleSign, and is returned in the response message immediately following the web service request.

status
object
code
string

This code describes the status of your transaction. You can use this code to programmatically respond. You are returned two types of codes, either status codes or error codes.

required
description
string

A text description of the status code.

required
updated_on
string

This is a timestamp showing when your transaction status was updated last.

required

Send a Test Request

$$.env
2 variables not set
username
password