layout: default.twig ---

Server API Reference

EnvayaSMS communicates with the server via HTTP POST requests that expect an XML response.

For convenience, EnvayaSMS includes server libraries and example code for certain languages to simplify handling its POST requests and generating response XML.

If a server library is not yet available for your programming language, you can still use EnvayaSMS by implementing code in accordance with the API reference below. We encourage you to contribute new libraries and example code back to the EnvayaSMS project!

HTTP Request Format

Example requests

In each of the example requests below, the Server URL is http://192.168.70.1:3000/sg/EnvayaSMS and the phone number of the phone with EnvayaSMS is 16505551212.

An incoming SMS from 6505551234 with message body "test":

POST /sg/EnvayaSMS HTTP/1.1
X-EnvayaSMS-Signature: sAemG31uRllk/K9xck2WRNaF/WI=
Content-Length: 96
Content-Type: application/x-www-form-urlencoded
Host: 192.168.70.1:3000
Connection: Keep-Alive

from=6505551234&message_type=sms&message=test&version=2&phone_number=16505551212&action=incoming

An incoming MMS message with an image/jpeg part and a text/plain part with message 'Test':

POST /sg/EnvayaSMS HTTP/1.1
X-EnvayaSMS-Signature: OgpiQet9guVhEp+0klrONR8qGNs=
Content-Length: 13087
Content-Type: multipart/form-data; boundary=i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Host: 192.168.70.1:3000
Connection: Keep-Alive

--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Content-Disposition: form-data; name="from"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

+16505551234
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Content-Disposition: form-data; name="message"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Test
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Content-Disposition: form-data; name="message_type"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mms
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Content-Disposition: form-data; name="mms_parts"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

[{"type":"application/smil","filename":"01smil","cid":"<0000>","name":"part0"},{"type":"text/plain","filename":"Text01.txt","cid":"<569>","name":"part1"},{"type":"image/jpeg","filename":"Image0001.jpg","cid":"<570>","name":"part2"}]
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Content-Disposition: form-data; name="version"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Content-Disposition: form-data; name="phone_number"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

16505551212
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Content-Disposition: form-data; name="action"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

incoming
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Content-Disposition: form-data; name="part0"; filename="01smil"
Content-Type: application/smil; charset=UTF-8
Content-Transfer-Encoding: binary

<smil>
  <head>
    <layout>
      <root-layout height="160" width="128"/>
      <region fit="meet" height="70%" id="Image" left="0%" top="30%" width="100%"/>
      <region fit="scroll" height="30%" id="Text" left="0%" top="0%" width="100%"/>
    </layout>
  </head>
  <body>
    <par dur="8000ms">
      <text region="Text" src="cid:569"/>
      <img region="Image" src="cid:570"/>
    </par>
  </body>
</smil>

--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Content-Disposition: form-data; name="part1"; filename="Text01.txt"
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: binary

Test
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO
Content-Disposition: form-data; name="part2"; filename="Image0001.jpg"
Content-Type: image/jpeg
Content-Transfer-Encoding: binary

BINARY IMAGE DATA
--i66xAht5IMn1Tfk7tL9DgY8ZHZxq0d0RGB6_wkjO--

Checking for outgoing SMS messages:

POST /sg/EnvayaSMS HTTP/1.1
X-EnvayaSMS-Signature: 139CL71b7r1Zw/E2wcccWFviSlg=
Content-Length: 50
Content-Type: application/x-www-form-urlencoded
Host: 192.168.70.1:3000
Connection: Keep-Alive

action=outgoing&version=2&phone_number=16505551212

Notifying the server of the status of a sent message:

POST /sg/EnvayaSMS HTTP/1.1
X-EnvayaSMS-Signature: 6uJtI6+QqlVBbUsR4T0WsQomods=
Content-Length: 80
Content-Type: application/x-www-form-urlencoded
Host: 192.168.70.1:3000
Connection: Keep-Alive

id=1536&status=sent&error=&action=send_status&version=2&phone_number=16505551212

Specification

The following parameters are sent in all POST requests from EnvayaSMS:

"version" ::= <integer>
EnvayaSMS's version code. This is an integer that will be incremented whenever a new version of EnvayaSMS is released. (It is not the same as the version name shown on the Help screen.)

This allows the server to support phones running different API versions at the same time. If a deployment has many phones running with EnvayaSMS, the server should update its code first, then the phones can be upgraded to the new version of EnvayaSMS as convenient.
"phone_number" ::= <text>
The phone number of the phone running EnvayaSMS, as entered under Menu > Settings.

This allows the server to differentiate between EnvayaSMS clients if multiple phones are running EnvayaSMS.
"action" ::= "outgoing" | "incoming" | "send_status"
The request action determines the purpose of the HTTP request:
"outgoing":
Poll the server for outgoing messages
"incoming":
Forward an incoming SMS or MMS message to the server
"send_status":
Update the server on the status of sending an outgoing message
The other POST parameters sent depend on the request action.
The following HTTP Headers are sent in all POST requests from EnvayaSMS:
"X-EnvayaSMS-Signature" ::= <text>
A signature of the request to verify the phone and the server share the same password. (This doesn't protect against MITM snooping or replay attacks, so it is recommended to use the https:// protocol.)

The signature is calculated by the following algorithm:
  1. Sort all POST parameters, not including file uploads, by the name of the field (in the usual ASCII order).
  2. Generate an input string by concatenating:
    • the server URL,
    • each of the sorted POST parameters with their corresponding values, and
    • the password,
    with a comma in between each element, like so:
    "<serverURL>,<name1>,<value1>,<...>,<nameN>,<valueN>,<password>"
  3. Generate the SHA-1 hash of the input string in UTF-8
  4. Encode the SHA-1 hash using Base64 with no line breaks.
Additional parameters sent in POST requests with action=incoming:
"from" ::= <text>
The phone number of the message sender.
"message_type" ::= "sms" | "mms"
Whether this message is an SMS or MMS.
"message" ::= <text>
The message body of the SMS, or the content of the text/plain part of the MMS.
Additional parameters sent in POST requests with action=incoming and message_type=mms:
"mms_parts" ::= <json_array>
Metadata for each part of the MMS. Each item in the JSON array is an object with the following keys and values:
"name" ::= <text>
The name of an additional form field where the content of the MMS part is sent as an attached file.
"cid" ::= <text>
The Content ID of the MMS part. This allows the server to resolve references in the SMIL part of the MMS (e.g. <img region="Image" src="cid:805"/>).
"type" ::= "application/smil" | "text/plain" | "image/jpeg" | ...
The Content Type of the MMS part.
"filename" ::= <text>
The filename of the MMS part, as sent by the sender phone, e.g. "Image001.jpg".
In addition, the request contains form fields with the content of each MMS part, with names as listed in the mms_parts field. Text parts are encoded in UTF-8.
Additional parameters sent in POST requests with action=outgoing:
(None)
Additional parameters sent in POST requests with action=send_status:
"id" ::= <text>
The Server's ID for the outgoing message (from the id attribute of an sms tag in a previous XML response from the server).
"status" ::= "queued" | "failed" | "sent"
The current status of the outgoing message.
"error" ::= <text>
A description of the reason for the error, if the message failed to send; or, an empty string if the message has been sent successfully.

HTTP Response Format

For a successul request, the server should return HTTP status code 200. If the signature check failed, the server should return status code 403. Other status codes may be used to signify errors.

HTTP response for action=incoming and action=outgoing

Example: 
HTTP/1.1 200 OK
Content-Type: text/xml
Content-Length: 189

<?xml version='1.0' encoding='UTF-8'?>
<messages>
  <sms id='1540' to='16505551213'>This is a test</sms>
  <sms id='1541' to='16505551214'>This is a another test message.</sms>
</messages>
Specification:

The Content-Type header should be text/xml, with the content as follows:

<messages>
The root XML element.

Attributes:
none

Content:
<sms>*
The SMS messages to send.
<sms>
Describes an outgoing SMS to send.

Attributes:
"id" ::= <text> (optional)
An ID for this outgoing message. (EnvayaSMS will send this back to the server as the id field in a send_status request.)
"to" ::= <text> (optional for incoming, required for outgoing)
The phone number to send the SMS to. If omitted for action=incoming, it will be sent as a reply to the original sender.

Content:
CDATA
The content of the SMS message to send.

HTTP Response for action=send_status

Example: 
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 2

OK

The response content for send_status requests is currently undefined and ignored. HTTP status code 200 signifies success, and anything else signifies failure.