SMS Nexus API Documentation

Authentication

All API requests require authentication using a Bearer token. You can generate API tokens from your dashboard under the API Keys section.

Include your token in the Authorization header of every request:

Authorization: Bearer your-api-token-here

Base URL

All API endpoints are relative to the following base URL:

https://www.smsnexus.net/api

Send an SMS or MMS message to a recipient. Requires a valid phone number in your account and sufficient credit balance.

Request Body

Example Request

curl -X POST https://www.smsnexus.net/api/sms/send \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "message": "Hello from SMS Nexus!"
  }'

Example Response

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "id": 12345,
    "from": "+15551234567",
    "to": "+15559876543",
    "body": "Hello from SMS Nexus!",
    "status": "queued",
    "credits_used": 1,
    "created_at": "2026-03-08T12:00:00Z"
  }
}

Retrieve your current credit balance.

Example Request

curl -X GET https://www.smsnexus.net/api/balance \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": {
    "credits": 5000,
    "currency": "credits",
    "plan": "Professional",
    "credits_used_today": 127
  }
}

Retrieve a paginated list of messages. Supports filtering by status, direction, and date range.

Query Parameters

Example Request

curl -X GET "https://www.smsnexus.net/api/messages?page=1&per_page=25&status=delivered" \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "from": "+15551234567",
      "to": "+15559876543",
      "body": "Hello!",
      "direction": "outbound",
      "status": "delivered",
      "credits_used": 1,
      "created_at": "2026-03-08T12:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 10,
    "per_page": 25,
    "total": 250
  }
}

List all phone numbers associated with your account, including their status and capabilities.

Example Request

curl -X GET https://www.smsnexus.net/api/phone-numbers \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "number": "+15551234567",
      "carrier": "bulkvs",
      "capabilities": ["sms", "mms"],
      "status": "active",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

List all conversations (message threads) in your account. Each conversation represents a unique pair of sender and recipient numbers.

Example Request

curl -X GET https://www.smsnexus.net/api/conversations \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 42,
      "phone_number": "+15551234567",
      "contact_number": "+15559876543",
      "last_message": "Thanks for your order!",
      "last_message_at": "2026-03-08T11:45:00Z",
      "unread_count": 0,
      "message_count": 15
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 25,
    "total": 67
  }
}

Webhooks

Register webhook URLs to receive real-time notifications for incoming messages, delivery status updates, and other events.

curl -X POST https://www.smsnexus.net/api/webhooks \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/sms",
    "events": ["message.received", "message.delivered"]
  }'

{
  "success": true,
  "data": {
    "id": 5,
    "url": "https://yourapp.com/webhooks/sms",
    "events": ["message.received", "message.delivered"],
    "active": true,
    "created_at": "2026-03-08T12:00:00Z"
  }
}

curl -X GET https://www.smsnexus.net/api/webhooks \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

{
  "success": true,
  "data": [
    {
      "id": 5,
      "url": "https://yourapp.com/webhooks/sms",
      "events": ["message.received", "message.delivered"],
      "active": true,
      "created_at": "2026-03-08T12:00:00Z"
    }
  ]
}

curl -X DELETE https://www.smsnexus.net/api/webhooks/5 \
  -H "Authorization: Bearer your-api-token" \
  -H "Accept: application/json"

{
  "success": true,
  "message": "Webhook deleted successfully"
}

Rate Limits

API requests are rate-limited to ensure fair usage and platform stability. Rate limit information is included in response headers.

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709892000

Error Codes

The API uses standard HTTP status codes to indicate success or failure. Error responses include a JSON body with details.

Error Response Format

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "to": ["The to field is required."],
    "message": ["The message field is required."]
  }
}