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.

Read more in our help center.

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
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
{
    "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
{
    "event_id": "09c829a2-a77b-422d-8562-2f88e784dfb5",
    "timestamp": "2025-04-01T11:50:12.003029+00:00",
    "event_type": "<event type indicator string>",
    "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
{
    "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"
    }
}

Signature Verification

All webhook events are timestamped in the envelope and signed, so the receiving servers are able to verify that the webhook request in fact came from the systems controlled by GatewayAPI.

The signature itself is in a header called Signature and follows the format v1={hex value of hmac digest}.

To calculate the expected signature of the request, calculate the HMAC-SHA-256 value of the request body, with the provided secret key defined when setting up the webhook delivery configuration in the GatewayAPI dashboard.

A note on key length

While generating the key for submission, rememeber that that a longer key provide an increase to the cryptographic strengh of the HMAC function.

But at some point, the extra strength of a longer key provides no benefit as the time to crack the key might already be in the range of thousands of years, and a longer key just creates an undue burden on the webhook delivery system.

Therefore, we have limited how long the keys can be.

An expample of a function that can check if the request is signed as expected, could be:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import hmac
import secrets

class Request:
    """Generic request model."""

    body: bytes
    headers: dict[str, str]

def verify_request(request: Request, signature_key: bytes) -> bool:
    signature = request.headers.get("Signature")
    if not signature:
        return False

    expected_signature = hmac.digest(
        signature_key,
        request.body,
        "SHA256",
    )
    return secrets.compare_digest(
        signature.removeprefix("v1="),
        expected_signature.hex(),
    )

Furthermore, the event is timestamped so older events can be rejected safely.

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.