Skip to content

Mobile Message API

This new API aims to be a simpler interface for sending messages to phone numbers, which as of right now means SMS but will soon also have the option to include RCS. By integrating with this API, you will be prepared for sending RCS without any need for changing anything in your code. The API simplifies a lot of things by removing the need for dealing with encoding or message classes. This is now handled automatically.

All API calls need to be made against either the domain messaging.gatewayapi.com or messaging.gatewayapi.eu, depending on your chosen setup.

The authentication is made with the Token in your API keys. This API does not support OAuth1 or legacy credentials.

A very basic example for sending a single message would be:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
POST /mobile/single HTTP/1.1
Host: messaging.gatewayapi.com
Authorization: Token hMvCn2w1St-3pgVuIoqB0HyCOINxduwZWQOQKkH2fLePBiAjPfpCOOpWiupRgqvm
Accept: application/json, text/javascript
Content-Type: application/json

{

    "sender": "ExampleSMS",
    "message": "Hello world!",
    "recipient": 4512345678

}

The successful response looks like:

1
2
3
4
5
6
7
{

    "msg_id": "01JNN696A9E0WS89FPYGT15NBX",
    "recipient": 4512345678,
    "reference": "<client provided reference>"

}

We provide a full OpenAPI spec, as well as Swagger and Redoc.

Webhook callbacks

The callback payload is in a format of an envelope that will always be the same:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{

    "event_id": "09c829a2-a77b-422d-8562-2f88e784dfb5",
    "timestamp": "2025-04-01T11:50:12.003029+00:00",
    "event_type": "messaging.status.sms",
    "event": {
        ...
    }

}

The event_type will indicate which type of event it is and different schemas will apply to the event object. Right now we only have message.status.sms defined, but more event types will follow like messaging.status.rcs for RCS messages.

A full payload for an SMS status:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{

    "event_id": "09c829a2-a77b-422d-8562-2f88e784dfb5",
    "timestamp": "2025-04-01T11:50:12.003029+00:00",
    "event_type": "messaging.status.sms",
    "event": {
        "msg_id": "01JQRJWK259Y1YEECJZB50908V",
        "recipient": 4512345678,
        "reference": "<client provided reference>",
        "status": "delivered",
        "status_at": "2025-04-01T11:49:12.005021+00:00"
    }

}

Changelog

An API needs to be reliable in terms of schema requirements and we will not introduce breaking changes without proper deprecation warnings. GatewayAPI has a good track record in that regard, as we have not changed the interface of our various APIs since their launch. That means that if you have made an integration, you can be sure that existing functionality will not require any code changes without proper warning.

Our definition of a breaking change is when fields are removed or change fundamental meaning. Addition of new fields and options are not seen as a breaking change, meaning you should make sure your system does not break if for example the JSON payload in callbacks will have additional fields. As the functionality expands on this API, there might be introduced different or more event types (the event_type field) to provide you with more data on your traffic.