eMsgNow

Authorization

API Key: The x-api-key header must be included with every request to authenticate the client. Requests without this header will return a 401 Unauthorized error.

Example:

x-api-key: YOUR_API_KEY

1. Send SMS

POST /sms

Sends an SMS message. The message can be directly specified or templated.

Headers

• x-api-key (required): API key for authorization.

Request Body

Sample Request (Non Templated)

{
    "to": "+1234567890",
    "from": "XXXXXXXXXX",
    "message": "Hello, this is a test SMS message."
}

Sample Request (Templated)

{
    "to" : "1234567890",
    "from" : "XXXXXXXXXX",
    "templateId" : "gPVTbWpwQHXgg8KSZ6sX",
    "clientId" : "23948729438slkdfjwkfjhsdfsdf",
    "variables" : {
        "name" : "Jane Doe",
        "etor" : "10:49pm"
    }
}

Sample Response

200 OK

{
    "message": "SMS received successfully",
    "trackingId": "1234567890abcdef"
}

Response Fields

Rate Limiting

To ensure fair usage of resources, the Send SMS API endpoint is rate-limited based on each client’s API key. If the rate limit is exceeded, subsequent requests will be temporarily blocked until the rate limit resets.

Current Rate Limit

The current rate limit may vary based on your subscription plan and usage agreement. Please refer to the API’s response headers to monitor your rate limit status, or contact us for your specific rate limit settings.

Rate Limit Headers

On each response, the following headers provide rate limit details:

Exceeded Rate Limit Response

If the rate limit is exceeded, the following response will be returned:

{
    "error": "Rate limit exceeded"
}

Increasing Rate Limit

If your application requires a higher rate limit, please reach out to the eMsgNow support team to discuss rate limit adjustments that suit your requirements. We are happy to accommodate higher traffic where possible. Contact us via email at support@emsgnow.com or through your eMsgNow representative.

2. Get SMS Details

GET /sms/:messageId

Retrieves the full details of an SMS message, including events related to the SMS.

Headers

• x-api-key (required): API key for authorization.

Sample Request

GET /sms/1234567890abcdef

Sample Response

{
    "to": "1234567890",
    "from": "XXXXXXXXXX",
    "message": "Utility Alert: We think your power is out",
    "clientId": "23948729438slkdfjwkfjhsdfsdf",
    "messageType": "sms",
    "trackingId": "1234567890abcdef",
    "notBefore": "2024-11-10T02:48:08.004Z",
    "notAfter": "2024-11-10T08:48:08.004Z",
    "created": "2024-11-10T18:18:31.050Z",
    "updated": "2024-11-10T18:18:31.050Z",
    "events": [
        {
            "id": "5mogLKKETFjg7c3eNNvH",
            "message": {
                "channel": "sms",
                "trackingId": ""1234567890abcdef",
                "clientId": "23948729438slkdfjwkfjhsdfsdf",
                "status": "processing",
                "statusAt": "2024-11-10T02:48:08.019Z",
                "additionalInfo": {}
            },
            "timestamp": "2024-11-10T18:18:31.050Z"
        },
        {
            "id": "C98OWsv63rVLJoE5QAns",
            "message": {
                "channel": "sms",
                "trackingId": ""1234567890abcdef",
                "clientId": "23948729438slkdfjwkfjhsdfsdf",
                "status": "sent to provider",
                "statusAt": "2024-11-10T02:48:08.019Z",
                "additionalInfo": {}
            },
            "timestamp": "2024-11-10T18:18:31.050Z"
        },
        {
            "id": "thwRO3qA1lJnsMv7zfbr",
            "message": {
                "channel": "sms",
                "trackingId": ""1234567890abcdef",
                "clientId": "23948729438slkdfjwkfjhsdfsdf",
                "status": "delivered",
                "statusAt": "2024-11-10T02:48:08.019Z",
                "additionalInfo": {}
            },
            "timestamp": "2024-11-10T18:18:31.050Z"
        }
    ]
}

Response Fields

Events Array

Each SMS can have multiple associated events with their own details.

3. Get SMS Events

GET /sms/:messageId/events

Retrieves a list of events associated with a specific SMS message.

Headers

• x-api-key (required): API key for authorization.

Sample Request

GET /sms/1234567890abcdef/events

Sample Response

{
    "messageId": "1234567890abcdef",
    "events": [
        {
            "id": "5mogLKKETFjg7c3eNNvH",
            "message": {
                "channel": "sms",
                "trackingId": ""1234567890abcdef",
                "clientId": "23948729438slkdfjwkfjhsdfsdf",
                "status": "processing",
                "statusAt": "2024-11-10T02:48:08.019Z",
                "additionalInfo": {}
            },
            "timestamp": "2024-11-10T18:18:31.050Z"
        },
        {
            "id": "C98OWsv63rVLJoE5QAns",
            "message": {
                "channel": "sms",
                "trackingId": ""1234567890abcdef",
                "clientId": "23948729438slkdfjwkfjhsdfsdf",
                "status": "sent to provider",
                "statusAt": "2024-11-10T02:48:08.019Z",
                "additionalInfo": {}
            },
            "timestamp": "2024-11-10T18:18:31.050Z"
        },
        {
            "id": "thwRO3qA1lJnsMv7zfbr",
            "message": {
                "channel": "sms",
                "trackingId": ""1234567890abcdef",
                "clientId": "23948729438slkdfjwkfjhsdfsdf",
                "status": "delivered",
                "statusAt": "2024-11-10T02:48:08.019Z",
                "additionalInfo": {}
            },
            "timestamp": "2024-11-10T18:18:31.050Z"
        }
    ]
}

Response Fields

Events Array

Each event object within the events array provides details about the status of the SMS message at different stages.

4. Get Single SMS Event

GET /sms/:messageId/events/:eventId

Retrieves a specific event associated with an SMS message.

Headers

• x-api-key (required): API key for authorization.

Sample Request

GET /sms/1234567890abcdef/events/5mogLKKETFjg7c3eNNvH

Sample Response

{
    "messageId": "1234567890abcdef",
    "id": "5mogLKKETFjg7c3eNNvH",
    "message": {
        "channel": "sms",
        "trackingId": "1234567890abcdef",
        "clientId": "1",
        "status": "processing",
        "statusAt": "2024-11-10T02:48:08.019Z",
        "additionalInfo": {}
    },
    "timestamp": "2024-11-10T18:18:31.050Z"
}

Get Single SMS Event Response Data

Message Object

The message object within the event provides additional details about the SMS status at the time of the event.

Error Responses

401 Unauthorized

{
    "error": "API key is required"
}

403 Forbidden

{
    "error": "Invalid API key"
}

500 Internal Server Error

{
    "error": "Failed to retrieve SMS status"
}

429 Too Many Requests

{
    "error": "Rate limit exceeded"
}