User Tools

Site Tools


red_api:http

Hyper Text Transfer Protocol (HTTP) API

The Red Oxygen HTTP API provides a simple interface for programmers to add SMS capability to their applications.

HTTP interface details

The Red Oxygen HTTP interface can be easily called from just about any programming language.

Features

  • Standard SMS 160 characters
  • Long SMS (Greater than 160 characters)
  • 2-Way messaging. (SMS replies sent to email address)
  • Use GET or POST
  • Can be used through firewalls and proxy servers

Sample code is provided for:

  • C# (C Sharp)
  • Java
  • ASP (Active Server Pages)
  • VB.Net

Server details

Primary Server: https://www2.redoxygen.net

Server Port: 80 (HTTP) or 443 (HTTPS)

Function SendSMS

Parameters

Name Description Example
AccountId This is your Red Oxygen Account ID, which uniquely identifies your account. CI00000001
Email This is the email address of your Red Oxygen user account. It is also the address that will receive replies to the sent SMS. username@company.com
Password This is the password of your Red Oxygen user account. secret
Recipient The destination mobile numbers. Multiple recipients can be specified comma separated. 61409000000,61419718927,61419718972
Message A single SMS has a maximum length of 160 characters. If the message is greater than 160 characters then multiple SMS will be sent as a concatenated SMS which will result in an additional charge for the additional messages. The maximum length of a message is 765 characters. If you exceed this limit only the first 765 characters of your message will be sent. Server 23 is offline.

Calling the Server

Parameters passed to the Red Oxygen SMS gateway can be passed via GET request or a POST request.

Please note: The limitation of making a GET call is that the total address line can only be 1000 characters long. So a large number of recipients might cause problem in one call. Please separate them into several calls.

The URL and Data must be URL encoded.

HTTP GET

With a GET request all parameters are passed in the address part of the request.

Example URL:

https://www2.redoxygen.net/sms.dll?Action=SendSMS&AccountId=CI00000001&Email=Username%40company%2Ecom&Password=secret&Recipient=61400000001&Message=Server+23+is+offline

HTTP POST

With a POST request the SendSMS command might look like this:

URL:

https://www2.redoxygen.net/sms.dll?Action=SendSMS

DATA:

AccountId=CI00000001&Email=Username%40company%2Ecom&Password=secret&Recipient=61400000001&Message=Server+23+is+offline

URL Encoding

URL Encoding means certain non alpha-numeric characters should be replaced with a ‘Percent’ symbol followed by the ASCII value of the character as 2 Hex digits. Eg. A space has ASCII code 32 which is 20 in Hex so it would be represented as %20. A . (Dot) character would be %2E, a @ symbol would be %40, etc.

For more information on URL encoding follow this link.

http://www.w3.org/International/O-URL-code.html

Accessing through a proxy server

The method for sending through proxy server will be language dependent.

Alternatively if you are using the Red Oxygen DLL, COM object, or Command Line tool they can be configured to use a proxy server.

Extended Format - Red Alert by HTTP format

The request must be a HTTP POST command and not a HTTP GET command.

HTTP Data format:

[SENDER]
ID=<AccountID>
[FROM]
Email=<email address of the user>
PW=<The users password>
[1]
Name=<Recipients name>
Number=<Recipients mobile phone number>
Message=<SMS message>
[2]
Name=<Recipients name>
Number=<Recipients mobile phone number>
Message=<SMS message>

Field Descriptions

Section Name Description Example
[SENDER] AccountID This is your Red Oxygen Account ID, which uniquely identifies your account. CI00000001
[FROM] Email This is the email address of your Red Oxygen user account. It is also the address that will receive replies to the sent SMS. username@company.com
PW (Optional) This field contains the user’s password. The user would need to be created by the customer’s system administrator. It is possible however to have new users automatically created if the customer can be authenticated by IP address and ‘Active Creation’ is enabled for the customers account. In the case of ‘Active Creation’ the password is not required. secret
[1] This section contains the details of the actual SMS message to send. The data section can contain data for multiple messages using sections [2], [3] and so on.
Name (Optional) This is the name of the recipient the message is being sent to. This becomes useful when the recipient replies to the SMS. The Name specified will be passed back to the user in the subject field of the email sent back to the user with the SMS replies message. John
Number This is the mobile phone number of the recipient. It should be formatted in full international 61409000000
Message A single SMS has a maximum length of 160 characters. If the message is greater than 160 characters then multiple SMS will be sent as a concatenated SMS which will result in an additional charge for the additional messages. The maximum length of a message is 765 characters. If you exceed this limit only the first 765 characters of your message will be sent. The text should be URL encoded to represent symbols Server 23 is offline.

Reply Path

When the SMS recipient replies with their mobile phone the message is returned to the address specified in the ‘Email’ field of the [FROM] section of the message data.

The ‘from’ address will be smsgateway@redoxygen.net

The Subject line will be ‘SMS Reply from <Name>’ where <Name> is replaced with the ‘Name’ specified in the [1] section.

Return Codes

The HTTP result code of 200 is returned if the Red Oxygen server successfully receives and processes the message, even if the there is an error in the processing. The HTTP result code just indicates the success or failure in connecting to the Red Oxygen server. Any errors in the actual processing of the request are returned in the body of the response. The format of the response is:

<Return Code><Space><Error description>

Where <Return Code> is ‘0000’ in a successful case. In the case of an error it is a 4 digit error code. In the case of ‘0000’ (Success) the error description is blank.

Example

Example 1: - Send one SMS - Authentication by password

URL: https://www2.redoxygen.net/sms.dll?private&type=0
DATA [SENDER]
ID=CI00000001

[FROM]
Email=support@redoxyen.com

[1]
Name=Jones
Number=61409000000
Message=Server 23 is offline.
RESPONSE 0000
SMS sent to 61409000000
MESSAGE: Server 23 is offline.

Example 2: - Send two SMS - Authentication by IP address

URL: https://www2.redoxygen.net/sms.dll?private&type=0
DATA [SENDER]
ID=CI00000001

[FROM]
Email=support@redoxyen.com

[1]
Name=Jones
Number=61409000000
Message=Server 23 is offline.

[2]
Name= Tim
Number=61419718927
Message=Server 24 is offline.
RESPONSE 0000
SMS sent to 61409000000
MESSAGE: Server 23 is offline.
SMS sent to 61419718927
MESSAGE: Server 24 is offline.
red_api/http.txt · Last modified: 2020/08/18 15:18 (external edit)