Skip to content

API

The API is hosted at https://api.nuudaysmsgateway.dk.

A very basic example of how to call the API could be something like:

POST /v1/sms/submit HTTP/1.1
Host: api.nuudaysmsgateway.dk
Authorization: Token NG.Vy3o3ctYZW45knn5mIQGQnTKo9rArcGf
Accept: application/json, text/javascript
Content-Type: application/json

{
    "text": "Hello World!",
    "recipient": 4512345678,
    "encoding": "gsm7",
    "sender": "ExampleSMS",
}

OpenAPI

In addition to the higher level documentation found here, the API includes an OpenAPI specification at https://api.nuudaysmsgateway.dk/docs/openapi.json. The OpenAPI specification can be used to generate client code or just be used to inspect the API in a known interface.

The OpenAPI specification can be interacted with using many different tools, but to make integration easier, we have bundled a few tools of a known version of these with our OpenAPI specification:

Connection Limitations

The API has several layers of protection to ensure the availability of the system.

This ranges from general firewall techniques to limiting how many SMS segments each account is able to submit within a given duration.

Firewall

The SMS gateway is protected by a firewall that limits excessive amounts of requests and/or connections coming to it, the exact configuration is subject to change as attacks and protection schemes evolve.

Regular use should not be restricted by the firewall, as it meant to be a limit on malicious use and misconfiguations.

Segments/second Rate Limit

Each account is configured to allow submission of a certain number of SMS segments per second. This limit can be exceeded, but only for short duration as the average request still cannot exceed the set limit.

Note that this limit is not based on the number of request, but is instead based on the segments of all messeges submitted.

Each SMS accepted by the API has a segment count, it is calculated by determining how long the byte length of the message is and how many messages the text needs to be divided into to be sent to the receiving device.

The elements that makes up factors in the calculation is the text, header, and encoding. The latter can make a big difference, as each character will take up more space using the UCS-2 encoding.

For shorter messages this is often 1, but up to 4 is not quite uncommon as well. These counts are stored by a time interval and is then checked when accepting new messages.

HTTP Version

Clients can connect with either HTTP/1.1 or HTTP/2. This allows the integrating software to take advantage of the version that is the most suitable for the specific case.