Paths

Retrieving the status report for an SMS

TEXT

GET /reports

Description

This method is used to retrieve information about an existing SMS. It requires as input the Job ID retrurned by the successful call to sendSMS, and it returns the corresponding status.

Possible return values are listed in the table below:

ProcessStatus	Status	Description	statusRequested
OPEN	<empty>	Pending SMS, not yet scheduled.	<Irrelevant>
OPEN	<any>	In re-try state (e.g., during a connection error to service provider).	<Irrelevant>
DONE	SUC_ACC	Successful ( without delivery notification).	False
DONE	SUC_FIN	Successful (with delivery notification).	True
DONE	INVALID_DST	Invalid number (e.g., 999999).	<Irrelevant>
DONE	BLOCKED	Blocklisted number.	<Irrelevant>
DONE	TIMEOUT	Sent, but the validity period was exceeded.	True
DONE	CON_ERR	Failed; all retry attempts were unsuccessful.	<Irrelevant>
DONE	FAILED_FIN	Failed; delivery notification returns this status.	True
DONE	NOT_ACC_FIN	Failed; delivery to the provider was/is not possible.	<Irrelevant>
DONE	SEND_ERR	Internal error (in most cases, the SMS has arrived anyway).	<Irrelevant>
DONE	STATUS_ERR	Internal error during the query for the delivery notification.	True
CANCELED	<empty>	Transmisson was cancelled before the initial delivery attempt.	<Irrelevant>
CANCELED	NOT_ACC_REC	Transmisson was cancelled after the initial delivery attempt.	<Irrelevant>
RUNNING	<any>	SMS was sent, but no delivery notification was received.	True
KILL	<any>	SMS was sent, but cancelled and no delivery notification has been received.	True

Parameters

Type	Name	Description	Schema
Query	jobid required	Retarus Job ID for a submitted SMS message/job, as returned by sendSMS	string
Query	pass required	Retarus API Password	string
Query	user required	Retarus API Login ID	string

Responses

HTTP code	Description	Schema
200	The information was successfully retrieved. The status is returned in the body. Example TEXT `HTTP/1.1 200 X-Application-Context: application Transfer-Encoding: chunked Date: Wed, 25 Oct 2017 11:59:32 GMT Status=SUC_FIN ProcessStatus=DONE`	No content
400	One or more parameters are invalid. Mandatory parameters might be missing.	No content
401	Authentication information is missing or invalid.	No content
405	The HTTP method used is not allowed on this resource.	No content
500	Internal Server Error. Please try again later or contact Retarus support.	No content

Sending an SMS to a single destination

TEXT

POST /sms

Description

This method is used to create and prepare SMS jobs to be transferred for processing. If a valid JobRequest has been received by the Webservice, the Webservice sends an ID back that must be specified by the client when querying the job status.

Parameters

Type	Name	Description	Schema	Default
Query	bc optional	Optional billing information can be entered here. Max. 70 characters	string
Query	dn optional	Requests a delivery notification. Default is No. The use of this option requires an additional fee.	boolean	“false“
Query	dst required	Recipient’s mobile phone number. If a number is specified without a country code, the value specified in the EAS configuration parameter Country code will automatically be applied.	string
Query	msg required	The SMS message text.	string
Query	pass required	Retarus API Password	string
Query	qos optional	Sets the priority of an SMS job. If you have time-critical SMS messages, we recommend that you select the express option. Supported values are: normal express An additional fee is required to send an express SMS.	enum (normal, express)	“normal”
Query	ref optional	Optional reference information that will be included in getSMSReport. max. 70 characters (192 for US-ASCII encoding).	string
Query	src optional	The Sender ID displayed to the recipient. When entering the Sender ID, note the following technical restrictions: If the Sender ID is exclusively numerical, a maximum of 20 numbers can be used. A + character is available for optional use. If alphanumeric characters are used, the maximum length is 11. The following characters can be used: CODE a-z, A-Z, 0-9, !"#$%&'()+, -./:;<=>?@[\]^_\`{\|}~ No other characters are permitted. Java regular expression* CODE `(.\\+\|)[0-9]{1,20}\|[a-zA-Z0 -9\\x20\\p{Punct}]{1,11}` p{Punct} stands for the following: CODE !"#$%&'()*+,-./:;<=>?@[\]^_`{\|}~ Invalid Sender IDs are corrected automatically (e.g., replaced with an X).	string
Query	user required	Retarus API Login ID	string

Responses

HTTP code	Description	Schema
201	The job was successfully submitted. The response contains the Job ID which can be used in subsequent calls to retrieve the status. Example TEXT `HTTP/1.1 201 X-Application-Context: application Transfer-Encoding: chunked Date: Wed, 25 Oct 2017 12:04:21 GMT J.20171025-140421.737-0j96zs9yi4B1V7OQ31`	No content
400	One or more parameters are invalid. Mandatory parameters might be missing.	No content
401	Authentication information is missing or invalid.	No content
405	The HTTP method used is not allowed on this resource.	No content
500	Internal Server Error. Please try again later or contact Retarus support.	No content