API Documentation (v0)
Welcome to the Emess API v0 documentation. All endpoints are prefixed with /api/v0. You must authenticate using your App ID and Secret Key to receive a JWT token.
POST/auth/token
Authenticate your application and receive a Bearer token.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| appId | string | Yes | Your application's App ID |
| secretKey | string | Yes | Your application's Secret Key |
Response
{
"token": "jwt_token_string"
}Possible Errors
- 400 Bad Request:
{ "message": "Missing appId or secretKey" } - 401 Unauthorized:
{ "message": "Invalid credentials" } - 500 Internal Server Error:
{ "message": "Server configuration error" }
POST/sms/send
Send a single SMS message. Requires a valid JWT Bearer token in the Authorization header.
Parameters (Body)
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| number | string | Yes | - | Recipient's phone number |
| message | string | Yes | - | The content of the SMS message |
| type | enum | Yes | - | Must be one of: critical, standard, or bulk |
| keepDiacritics | boolean | No | false | If true, prevents automatic removal of diacritics/accents from the message text. Recommended value is false |
Response
{
"message": "SMS sent successfully",
"id": "msg_uuid",
"batchId": "batch_uuid"
}Possible Errors
- 400 Bad Request: Missing parameters or invalid message type.
- 401 Unauthorized: App authentication failed (invalid/missing token).
- 402 Payment Required: Insufficient tokens in your organization.
- 500 Internal Server Error: Failed to send SMS or record the transaction.
POST/sms/bulk
Send the same SMS message to multiple numbers. Requires a valid JWT Bearer token in the Authorization header.
Parameters (Body)
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| numbers | array[string] | Yes | - | Array of recipient phone numbers |
| message | string | Yes | - | The content of the SMS message |
| type | enum | No | bulk | Must be one of: critical, standard, or bulk |
| keepDiacritics | boolean | No | false | If true, prevents automatic removal of diacritics/accents from the message text. Recommended value is false |
Response
{
"message": "Bulk processing completed",
"total": 100,
"data": ["msg_id_1", "msg_id_2"],
"succeeded": 100,
"failed": 0,
"batchId": "batch_uuid"
}Possible Errors
- 400 Bad Request: Missing numbers array or message.
- 401 Unauthorized: App authentication failed.
- 402 Payment Required: Insufficient tokens for the entire batch.