Outgoing SMS - Advanced Usage

This page outlines how you can take advantage of the advanced options sending out SMSes.

Advanced Usage

API Call

POST /v2/mtsms

The root element can be either a dict with a single SMS or a list of SMS’es.

Request, Response and Error

Request JSON Object

• message (string) – The content of the SMS, always specified in UTF-8 encoding, which we will transcode depending on the “encoding” field. The default is the usual GSM 03.38 encoding. Required unless payload is specified.
• sender (string) – Up to 11 alphanumeric characters, or 15 digits, that will be shown as the sender of the SMS. See SMS Sender
• tags (array) – A list of string tags, which will be replaced with the tag values for each recipient.
• label (string) – A label added to each sent message, can be used to uniquely identify a customer or company that you sent the message on behalf of, to help with invoicing your customers. If specied it must be the same for all messages in the request.
• recipients (array) – Array of recipients, described below. The number of recipients in a single message is limited to 10.000. required

Request JSON Array of Objects

• msisdn (string) – MSISDN aka the full mobile phone number of the recipient. Duplicates are not allowed in the same message. required
• charge (object) – Charge data. See Overcharged SMSes.
• tagvalues (array) – A list of string values corresponding to the tags in message. The order and amount of tag values must exactly match the tags.

Response JSON Object

• ids (array) – If successful you receive a object containing a list of message ids.

Error Codes

• 200 OK – Returns a dict with message IDs on success
• 400 Bad Request – Ie. invalid arguments, details in the JSON body
• 401 Unauthorized – Ie. invalid API key or signature
• 403 Forbidden – Ie. unauthorized ip address
• 422 Unprocessable Entity – Invalid json request body
• 500 Internal Server Error – If the request can’t be processed due to an exception. The exception details is returned in the JSON body

Examples

Fully fledged request: This is a bit of contrived example since message and payload can’t both be set at the same time, but it shows every possible field in the API like multiple recipients to the same message and multiple messages in the same payload.

Example Request

POST /v2/mtsms/?token=API-token HTTP/1.1
Host: sms.mavorion.com
Accept: application/json, text/javascript
Content-Type: application/json
{
    "token": "Xks23kDEksU78skS",
    "sender": "InfoSMS",
    "recipients": [
        {
            "msisdn": "9801247606",
            "tagvalues": [
                "Vader",
                "Darth"
            ]
        },
        {
            "msisdn": 9801247607
        }
    ],
    "tags": [
        "--Lastname--",
        "%Firstname"
    ],
    "message": "Hello World, regards %Firstname, --Lastname--",
    "label": "Mavorion Inc",
    "dry_run": "1"
}

Example Response

If the request succeed, the internal message identifiers are returned to the caller like this:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ids": [
        {
            "id": 110,
            "msisdn": "9801247606",
            "message": "Hello World, regards Darth, Vader"
        },
        {
            "id": 111,
            "msisdn": 9801247607,
            "message": "Hello World, regards %Firstname, --Lastname--"
        }
    ],
    "credit_consumed": 2
}

Please note that this response is subject to change and will continually, be updated to contain more useful data.

If the request fails, the response will look like the example below:

Tip

For more examples, check out the Examples Page.

List of error codes

For a complete list of the various codes see API Errors.