SMSPORTAL outbound API

Used to deliver SMS messages

Sending message

URL : https://api.smsportal.ch/sendsms

Method : POST GET

Auth required : YES

The following authentication methods are supported:

• Token-based authentication (recommended)
  Token-based method uses a tokens generated from Sms Portal platform to authenticate. Token may have an expiration time or be revoked at any time. It’s more secure and faster method compared to the password-based authentication.

  To send a request using token-based authentication, you need to:

  1. Build a string of the form username:api-token
  2. Encode the string to Base64
  3. Supply an authorization header with format Authorization: Basic {encoded-string}

• Password-based authentication (legacy)
  Password-based method uses a username and password to authenticate. We recommended that you don’t use password-based authentication, except for legacy tools and scripts. It’s much less secure method than token-based and slower due to cryptographic hash function.

  To send a request using password-based authentication, you need to:

  • For POST method supply a username and password as a part of request body
  • For GET method supply a username and password as query parameters

  as shown in the two examples below.

Data structure for POST (JSON object)

{
     "msgId"    : "UUID (optional)",
     "auth"     : {
                    "username": "string",
                    "password": "string"
                  },
     "sender"   : "string",
     "receiver" : "string",
     "mclass"   : "integer (optional)",
     "coding"   : "integer (optional)",
     "text"     : "string",
     "dlrMask"  : "integer (optional)",
     "dlrUrl"   : "string (optional)"
}

Parameters description

Example Calls

Token-based Authentication (Recommended)

POST Call Example

POST /sendsms HTTP/1.1
Host: api.smsportal.ch
Authorization: Basic dXNlcm5hbWU6YXBpLXRva2Vu
Content-Type: application/json

{
  "msgId": "4734f81a-7d63-478f-a0c7-f4a2dd595a71",
  "sender": "Test",
  "receiver": "41000000001",
  "mclass": 1,
  "coding": 0,
  "text": "This is a test message",
  "dlrMask": 19,
  "dlrUrl": "http://customer.biz/dlr-url"
}

GET Call Example

GET /sendsms?sender=Test&receiver=41000000001&text=This%20is%20a%20test%20message&dlrUrl=http%3A%2F%2Fcustomer.biz%2Fdlr-url&dlrMask=19 HTTP/1.1

Host: api.smsportal.ch
Authorization: Basic dXNlcm5hbWU6YXBpLXRva2Vu

⚠ The token string must be Base64 encoded and sent in the "Authorization" header.

Legacy Username/Password Authentication

POST Call Example

POST /sendsms HTTP/1.1
Host: api.smsportal.ch
Content-Type: application/json

{
  "msgId": "4734f81a-7d63-478f-a0c7-f4a2dd595a71",
  "auth": {
    "username": "user",
    "password": "pass"
  },
  "sender": "Test",
  "receiver": "41000000001",
  "mclass": 1,
  "coding": 0,
  "text": "This is a test message",
  "dlrMask": 19,
  "dlrUrl": "http://customer.biz/dlr-url"
}

GET Call Example

GET /sendsms?username=user&password=pass&sender=Test&receiver=41000000001&text=This%20is%20a%20test%20message&dlrUrl=http%3A%2F%2Fcustomer.biz%2Fdlr-url&dlrMask=19 HTTP/1.1

⚠ Get calls must be percent encoded
https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding

Success Response

Code : 202 Accepted

Content example

{
  "msgId": "4734f81a-7d63-478f-a0c7-f4a2dd595a71"
}

Error Response

Code : 403 Forbidden

Condition : If ‘username’ and ‘password’ combination is wrong.

Code : 400 Bad request

Condition : If object structure is invalid

Content example

{
  "reason": "JSON parse error: Unexpected character ('}' "
}

DLR Reports

DLR reports are deliver to the given dlrUrl parameter as a GET call with parameters:

msgId the id our API reply with when accepting message for processing, this can be given on API call or generated by our system.

report this is a structure of a Delivery Receipt Format specified in SMPP protocol, see description below.

Example call

http://customer.biz/dlr-url?msgId=4734f81a-7d63-478f-a0c7-f4a2dd595a71&report=id%3A54ab9a3c-d97b-49fd-9b1b-1a03dcc9f463+sub%3A001+dlvrd%3A000+submit+date%3A200430092654+done+date%3A200430092654+stat%3AACCEPTD+err%3A000+text%3A'

data is URL-Encoded

Delivery Receipt Format (as described in SMPP protocol specification v3.4)

The format for this Delivery Receipt
message is SMSC vendor specific but following is a typical example of Delivery Receipt report.

id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD err:E Text:......

The fields of the above delivery receipt example are explained in the following
table:

Example Delivery Receipt message states: