ExoSend API Documentation

Postman collection →

Introduction

Multi-tenant SMS microservice platform providing reliable SMS delivery through provider integrations.

Welcome to the ExoSend API documentation. This API allows you to send SMS messages, manage sender IDs, and monitor delivery status.

Getting Started

  1. Obtain API Token: Login to your ExoSend admin panel and navigate to your profile to generate an API token.
  2. Authentication: Include your token in the Authorization: Bearer {token} header for all requests.
  3. Base URL: All API requests should be made to the base URL shown above

Rate Limiting

API requests are rate-limited per organization. The default limit is 60 requests per minute. Contact support if you need higher limits.

Credits System

ExoSend uses a prepaid credits system. Each SMS message deducts credits based on the destination country and message length. Check your balance via the /balance endpoint.

As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_API_TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your API token by logging into the ExoSend admin panel at /admin and navigating to your profile settings. Click Create New Token to generate an API token.

Account Management

APIs for managing your ExoSend account balance and credits.

Get Credit Balance

GET
https://send.exoclass.com
/api/v1/balance
requires authentication

Retrieve your organization's current credit balance. Credits are used to send SMS messages, with costs varying by destination country and message length.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://send.exoclass.com/api/v1/balance" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "success": true,
    "data": {
        "balance": 99.965,
        "currency": "EUR",
        "organization": "ExoClass"
    }
}

SMS Operations

APIs for sending SMS messages and checking delivery status.

Send Single SMS

POST
https://send.exoclass.com
/api/v1/sms/send
requires authentication

Queue a single SMS message for delivery. The message will be sent asynchronously and credits will be deducted immediately.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://send.exoclass.com/api/v1/sms/send" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"recipient\": \"+37061234567\",
    \"message\": \"Hello from ExoSend! Your verification code is 123456.\",
    \"sender_id\": \"EXOCLASS\"
}"
Example response:
{
    "success": true,
    "data": {
        "message_id": "9a7f2e5c-1234-5678-90ab-cdef12345678",
        "status": "pending",
        "cost": 0.035,
        "segments": 1,
        "balance_remaining": 99.965
    },
    "message": "SMS queued for sending"
}
{
    "success": false,
    "error": {
        "code": "SENDER_NOT_FOUND",
        "message": "The specified sender ID was not found in your organization",
        "details": {
            "sender_id": "NONEXISTENT"
        }
    }
}
{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your account does not have enough credits",
        "details": {
            "required": 0.035,
            "available": 0
        }
    }
}
{
    "success": false,
    "error": {
        "code": "INVALID_PHONE_NUMBER",
        "message": "The recipient phone number is invalid",
        "details": {
            "recipient": "1234567890"
        }
    }
}
{
    "success": false,
    "error": {
        "code": "SENDER_NOT_VERIFIED",
        "message": "The sender ID must be verified before sending messages",
        "details": {
            "sender_id": "EXOCLASS",
            "status": "pending",
            "status_label": "Pending Review"
        }
    }
}

Send Bulk SMS

POST
https://send.exoclass.com
/api/v1/sms/send-bulk
requires authentication

Queue multiple SMS messages to different recipients with the same content. Invalid phone numbers will be filtered out, and only valid recipients will receive messages. Credits are deducted for all valid recipients before sending.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://send.exoclass.com/api/v1/sms/send-bulk" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"recipients\": [
        \"+37061234567\",
        \"+37061234568\",
        \"+37061234569\"
    ],
    \"message\": \"Bulk notification: System maintenance scheduled for tonight.\",
    \"sender_id\": \"EXOCLASS\"
}"
Example response:
{
    "success": true,
    "data": {
        "total_messages": 3,
        "total_cost": 0.105,
        "balance_remaining": 99.895,
        "message_ids": [
            "9a7f2e5c-1234-5678-90ab-cdef12345678",
            "9a7f2e5c-1234-5678-90ab-cdef12345679",
            "9a7f2e5c-1234-5678-90ab-cdef12345680"
        ],
        "invalid_recipients": []
    },
    "message": "Bulk SMS queued for sending"
}
{
    "success": true,
    "data": {
        "total_messages": 2,
        "total_cost": 0.07,
        "balance_remaining": 99.93,
        "message_ids": [
            "9a7f2e5c-1234-5678-90ab-cdef12345678",
            "9a7f2e5c-1234-5678-90ab-cdef12345679"
        ],
        "invalid_recipients": [
            "invalid-number"
        ]
    },
    "message": "Bulk SMS queued for sending"
}
{
    "success": false,
    "error": {
        "code": "NO_VALID_RECIPIENTS",
        "message": "No valid recipients found",
        "details": {
            "invalid_recipients": [
                "invalid1",
                "invalid2"
            ]
        }
    }
}
{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your account does not have enough credits",
        "details": {
            "required": 0.105,
            "available": 0.05,
            "valid_recipients_count": 3
        }
    }
}

Get Message Status

GET
https://send.exoclass.com
/api/v1/sms/{id}/status
requires authentication

Retrieve the current delivery status of a previously sent SMS message. Only messages belonging to your organization can be accessed.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

id
string
required

The UUID of the message.

Example:
9a7f2e5c-1234-5678-90ab-cdef12345678
Example request: 
curl --request GET \
    --get "https://send.exoclass.com/api/v1/sms/9a7f2e5c-1234-5678-90ab-cdef12345678/status" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "success": true,
    "data": {
        "id": "9a7f2e5c-1234-5678-90ab-cdef12345678",
        "status": "delivered",
        "recipient": "+37061234567",
        "cost": 0.035,
        "segments": 1,
        "sent_at": "2026-01-03T14:30:00+00:00",
        "delivered_at": "2026-01-03T14:30:15+00:00",
        "error_message": null,
        "error_code": null
    }
}
{
    "success": true,
    "data": {
        "id": "9a7f2e5c-1234-5678-90ab-cdef12345678",
        "status": "failed",
        "recipient": "+37061234567",
        "cost": 0.035,
        "segments": 1,
        "sent_at": null,
        "delivered_at": null,
        "error_message": "Invalid recipient",
        "error_code": "INVALID_RECIPIENT"
    }
}
{
    "success": false,
    "error": {
        "code": "NOT_FOUND",
        "message": "Message not found"
    }
}

Sender ID Management

APIs for managing sender IDs (sender names that appear on SMS messages). Sender IDs must be approved by administrators and verified by providers before use.

List Sender IDs

GET
https://send.exoclass.com
/api/v1/sender-ids
requires authentication

Retrieve all sender IDs for your organization with optional status filtering. By default, only verified sender IDs are returned.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

status
string

Filter by status. Options: verified, pending, approved, rejected, all. Default: verified.

Example:
verified
Example request: 
curl --request GET \
    --get "https://send.exoclass.com/api/v1/sender-ids?status=verified" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "success": true,
    "data": [
        {
            "id": "9a7f2e5c-1234-5678-90ab-cdef12345678",
            "sender_id": "EXOCLASS",
            "admin_status": "approved",
            "provider_status": "verified",
            "is_verified": true,
            "is_default": true,
            "rejection_reason": null,
            "message_count": 42,
            "created_at": "2026-01-01T10:00:00+00:00",
            "approved_at": "2026-01-01T12:00:00+00:00",
            "verified_at": "2026-01-01T14:00:00+00:00"
        },
        {
            "id": "9a7f2e5c-1234-5678-90ab-cdef12345679",
            "sender_id": "EXOSMS",
            "admin_status": "approved",
            "provider_status": "verified",
            "is_verified": true,
            "is_default": false,
            "rejection_reason": null,
            "message_count": 15,
            "created_at": "2026-01-02T10:00:00+00:00",
            "approved_at": "2026-01-02T11:00:00+00:00",
            "verified_at": "2026-01-02T13:00:00+00:00"
        }
    ]
}

Request New Sender ID

POST
https://send.exoclass.com
/api/v1/sender-ids
requires authentication

Submit a new sender ID request for approval. The sender ID will be created in pending status and must go through a two-stage approval process:

  1. Admin approval (manual review by ExoSend administrators)
  2. Provider verification (automatic verification with SMS provider)

Only after both stages can the sender ID be used for sending messages.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://send.exoclass.com/api/v1/sender-ids" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"sender_id\": \"EXOCLASS\"
}"
Example response:
{
    "success": true,
    "data": {
        "id": "9a7f2e5c-1234-5678-90ab-cdef12345678",
        "sender_id": "EXOCLASS",
        "admin_status": "pending",
        "provider_status": "pending",
        "is_verified": false,
        "is_default": false,
        "created_at": "2026-01-03T14:30:00+00:00"
    },
    "message": "Sender ID request submitted. Awaiting approval from administrator."
}
{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "The given data was invalid",
        "details": {
            "sender_id": [
                "The sender id must be between 3 and 11 characters."
            ]
        }
    }
}

Set Default Sender ID

PATCH
https://send.exoclass.com
/api/v1/sender-ids/{id}/default
requires authentication

Set a verified sender ID as the default for your organization. Only verified sender IDs can be set as default. Automatically unsets any previously set default sender ID.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

id
string
required

The UUID of the sender ID.

Example:
9a7f2e5c-1234-5678-90ab-cdef12345678
Example request: 
curl --request PATCH \
    "https://send.exoclass.com/api/v1/sender-ids/9a7f2e5c-1234-5678-90ab-cdef12345678/default" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "success": true,
    "data": {
        "id": "9a7f2e5c-1234-5678-90ab-cdef12345678",
        "sender_id": "EXOCLASS",
        "is_verified": true,
        "is_default": true
    },
    "message": "Sender ID set as default"
}
{
    "success": false,
    "error": {
        "code": "NOT_FOUND",
        "message": "Sender ID not found"
    }
}
{
    "success": false,
    "error": {
        "code": "NOT_VERIFIED",
        "message": "Only verified sender IDs can be set as default. Current status: pending approval."
    }
}

Delete Sender ID

DELETE
https://send.exoclass.com
/api/v1/sender-ids/{id}
requires authentication

Delete a sender ID from your organization. Sender IDs with existing messages or set as default cannot be deleted.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

id
string
required

The UUID of the sender ID.

Example:
9a7f2e5c-1234-5678-90ab-cdef12345678
Example request: 
curl --request DELETE \
    "https://send.exoclass.com/api/v1/sender-ids/9a7f2e5c-1234-5678-90ab-cdef12345678" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "success": true,
    "data": null,
    "message": "Sender ID deleted successfully"
}
{
    "success": false,
    "error": {
        "code": "NOT_FOUND",
        "message": "Sender ID not found"
    }
}
{
    "success": false,
    "error": {
        "code": "IS_DEFAULT",
        "message": "Cannot delete the default sender ID. Set another as default first."
    }
}
{
    "success": false,
    "error": {
        "code": "HAS_MESSAGES",
        "message": "Cannot delete sender ID with existing messages",
        "details": {
            "message_count": 42
        }
    }
}