SMS From Me

Automatically Start One on One SMS Conversations

REST API Message Object

Message Object

A complete message object includes the following fields. In many cases, though, functions do not return all the fields. It may be as short as just the identifier ("id").

  "message": {
    "id": "123",
    "destination": "9165551212",
    "message": "This is your text message",
    "created_on": "2017-08-01 15:18:22",
    "send_on": "2017-08-01 15:18:22",
    "status": "N",
    "status_date": "2017-08-01 15:18:22",
    "source": "api",
    "failure_count": 0
  "links": {
    "list": {
      "method": "GET",
      "url": ""
    "next": {
      "method": "NEXT",
      "url": ""
    "new": {
      "method": "POST",
      "url": ""
    "get": {
      "method": "GET",
      "url": ""
    "edit": {
      "method": "PATCH",
      "url": ""
    "delete": {
      "method": "DELETE",
      "url": ""
    "success": {
      "method": "PUT",
      "url": ""
    "failure": {
      "method": "PUT",
      "url": ""

"id" -- this field represents the message identifier. It can be used to access a message directly with a URL that looks like /api/1/message/<id> (without the < and > characters, of course.) Pretty much an reply that involves a message will include an "id".

"destination" -- the destination phone number, where the text message will be sent. This parameter can be edited with the PATCH method (edit link).

All numbers that end with 5551212 can be used to test a successful message. These will never be sent to anyone (the telephony will be ignored.)

All numbers that end with 5551213 can be used to test a failed message. These will never be sent to anyone (the telephony will be ignored,) but the result will always be negative.

"message" -- the actual text message that is to be sent or was sent. This parameter can be edited with the PATCH method (edit link).

"created_on" -- the date when this message was created. The timezone is always UTC.

"send_on" -- the date when this message is to be sent the soonest. It is likely to be sent a little later depending on the various settings you have. The timezone is always UTC. This parameter can be edited with the PATCH method (edit link).

"status" -- the current status of the message. The status is one letter which represent one of the following:

  • [N]ew -- the message was created and not yet sent.
  • [S]ent -- the message was sent successfully. This status cannot change anymore.
  • [E]rror -- the message could not be sent. The system will try again.
  • [F]ailed -- the message could not be sent. The system tried five times and always got an error. This status cannot change anymore.
  • [D]eleted -- the message was deleted before it was sent or failed.
  • [L]ocked -- the message was locked before it was sent or failed.
  • [B]lacklisted -- the "destination" parameter is a phone number present in our Do Not Text List. This status cannot be changed.

"status_date" -- the date and time when the "status" parameter was last changed. The date is quite useful when the status is "S", "F", and "B".

"source" -- how this message was created. It can be one of the following at the moment:

  • website -- the message was added using the Send a Message button in your Dashboard.
  • api -- the message was added using the REST API.
  • url -- the message was added using the URL capability.
  • email -- the message was email to

"failure_count" -- the number of times the SMS From Me system tried to send the message and it resulted in an error. This is a number from 0 to 5 at the moment. If 0, then the message was either sent successfully or there was no attempts yet. If 1 to 4, then attempts to send the message were made and all failed. If 5 then the status will be "Failed".

GET /api/1/message -- list messages

This command allows you to retrieve a list of messages.

The returned JSON is an object with one "messages" field which represents an array of messages.

  "messages": [
      "message": { ... },
      "links": { ... }
      "message": { ... },
      "links": { ... }

This command supports a filter parameter, as a query string. The filter is a JSON object that can include any combinaison of the following members:

  • filter: <filter name>
    • normal -- the messages that are still marked as new or were marked as erroneous
    • all -- all messages, whetever their status
    • error -- only messages that generated an error when sent
    • sent -- message was successfully sent
    • new -- message is new, the phone has not yet attempted to send it or is just now running an attempt
    • failed -- the phone tried to send that message five times at different times and always failed
    • deleted -- the message was deleted; the user can go to the Internet interface to undelete a deleted message
    • locked -- the message is currently locked
    • blocked -- the destination cell phone is blocked (a.k.a. on our Do Not Text List)
  • start: The starting point
    • defaults to 0,
    • has to be a number,
    • the first message is at offset 0 (not 1),
    • negative values are not valid,
    • if too large, then the query returns an empty array of messages.
  • count: The number of messages to return in this request
    • defaults to 50,
    • it has to be at least 1,
    • it has to be at most 100.
  • order: The order
    • the default is "desc",
    • "desc", to read the messages from the last to the first,
    • "asc", to read the messages from the first to the last.

The following represents the default:


WARNING: the JSON code will have to be URL encoded (not shown in sample above!). In JavaScript this would be done with encodeURIComponent(). In PHP, use the urlencode() function. In Java, you want to look at the URLEncoder.encode(result_json.toString(), "UTF-8") function.

The start and count parameters are used to allow paging while reading the list of messages.

IMPORTANT NOTE: A RESTful API is expected to return idempotent data, which means if you use the same URI twice with the same method and that method is one of GET, HEAD, OPTIONS, then the result should always be the same.

Unfortunately the SMS From Me list of messages changes as messages get added, sent, fail being sent, etc. In other words the list GET query is not quite idempotent by default.

To make this GET mostly idempotent, you want to change the order to "asc" and the filter to "all". Since once in a while we have a database clean up of older messages, if you attempt two GET requests, one before the clean up and one after, then you may see a discrepancy if some older messages were deleted just at that time. But it is much less likely.{"order":"asc","filter":"all"}

NEXT /api/1/message -- next messages

Retrieve the next message that the phone is expected to send.

If there are no more messages to be sent, then the function returns a 404 error: "not_a_message".

Note: This URL is accessible when the App Key is used to generate an OAuth token.

P.S. We still support the GET implementation, which is GET /api/1/message/next. This can be more practical in some applications but may get removed at a later time.

POST /api/1/message -- create a message

This command creates a new message. The POST must include a "message" parameter which is a JSON object representing the new message.

The JSON must include at least a "destination" and a "message" field. Optionally, it can include a "send_on" field.

If the "send_on" parameter is specified, it has to be a valid date defined as "YYYY-MM-DD HH:MM:SS".

  "message":"The text message to send to 9165551212",
  "send_on":"2017-01-01 00:00:00"

If the creation succeeds, the command returns a JSON with a full message.

Note: this function should return HTTP code 201. At the moment it returns 200 instead. You should plan on receiving a 201 at some point.

GET /api/1/message/<message identifier> -- read a message

Retrieve the specified message from the database. The result is a JSON representing the message. If the specified message identifier is incorrect or the message is not owned by the user represented by the given OAuth token, then a "not_a_message" error is generated and returned with a 404 HTTP code.

Please do not attempt to read all your messages just by starting the message identifier at 1 and increment by 1 until some random number. Instead, use the GET /api/1/message command to retrieve the list of your messages. It will be a lot faster.

PATCH /api/1/message/<message identifier> -- edit a message

The PATCH command can be used to do editing of a message. Only messages that were not yet sent (that have a status of New or Error) can be PATCHed.

The fields that can be PATCHed are limited to the "destination", the text "message" and the "send_on" date. These values have to be defined in the body (as if you were sending a POST.) You have to define the the fields in a JSON and set the "message" variable in the POST data equal to that JSON contents.

All the fields are optional, but at least one has be set or you will get an "invalid_request" error.

There is an example of a message parameter one can send along the PATCH command:

  "message":"Updating the text message!",

WARNING: In the example above the JSON is shown on multiple lines and unencoded. See this other WARNING for details.

On success the function returns a JSON with the message with only the message identifier.

DELETE /api/1/message/<message identifier> -- delete a message

This command deletes the specified message. Once deleted, the message cannot be accessed.

If the command works, it returns a JSON with the message identifier representing the message that was just deleted. That JSON will not include any links since once deleted a message cannot be accessed again.

If the message is not found then the function returns an error "not_a_message".

Note that this function is not idempotent. Once a message was deleted, trying to delete it again will return a 404 error "not_a_message".

PUT /api/1/message/<message identifier>/success -- mark message as successfully sent

This special URL is used to mark the message as successfully sent. This is used by the phone application after a valid send text message.

The result is to change the state of the message from New or Error to Sent.

The PUT comes with a JSON object, the one field is "parts" which gives you the number of parts that were required to send that text message (i.e. longer messages may require multiple parts to send them, normal messages use 1 part.)

  "parts": 1

PUT /api/1/message/<message identifier>/failure -- mark message as failed

This special URL is used to mark the message as failed. This is used by the phone application after a send text message failed.

In this case, the failure counter is increased by 1. If the number of failures is already 5, then we mark the message as a Failure, otherwise we mark it as an Error. A message marked as a Failure is abandonned. The system will not attempt to send it again. A message marked as an Error is tried again after a longer than normal period of time (i.e. the server makes it wait an extra 15 minutes times the number of failures so far.)

The PUT includes a JSON that defines an error message.

  "error_message": "textual description of the telephony error",




If you already registered with your email address and needed to re-validate (i.e. the first validation somehow failed) then go to the Validate Page where you can request for a new validation code to be emailed to you.

Login         Register         Get App.

Get My Free Book About SMS Marketing

Hey! Before you leave, make sure to get my freeBook About SMS Marketing. All you have to do is enter your email address and I'll send you a link to this website where you can retrieve your own copy of my free book.

Connect With Us
Google Plus Button
LinkedIn Button
YouTube Button