API Reference

All API requests require authentication via API key. Include your key in the X-API-Key header:

curl https://smstunnel.io/api/v1/sms/send \
  -H "X-API-Key: sk_live_abc123xyz" \
  -H "Content-Type: application/json"

API Key Format

• sk_live_* - Production keys
• sk_test_* - Test keys (sandbox mode)

Rate limits depend on your subscription plan:

Rate Limit Headers

All responses include rate limit information:

The API uses standard HTTP status codes and returns detailed error messages:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily SMS limit exceeded. Upgrade your plan for more.",
    "details": {
      "limit": 10,
      "used": 10,
      "resetAt": "2025-01-03T00:00:00Z"
    }
  }
}

Error Codes

Send an SMS message to a phone number.

Request Body

Example Request

curl -X POST https://smstunnel.io/api/v1/sms/send \
  -H "X-API-Key: sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+40712345678",
    "message": "Hello from SMSTunnel!"
  }'

Response

{
  "success": true,
  "data": {
    "messageId": "msg_abc123xyz789",
    "status": "queued",
    "phoneNumber": "+40712345678",
    "createdAt": "2025-01-02T10:30:00Z"
  }
}

Send a 2FA/OTP code with priority delivery. Separate rate limits apply.

Request Body

Example

curl -X POST https://smstunnel.io/api/v1/sms/2fa \
  -H "X-API-Key: sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+40712345678",
    "template": "Your code: {code}. Valid 5 min.",
    "expiresIn": 300
  }'

Get the delivery status of a sent message.

Response

{
  "success": true,
  "data": {
    "messageId": "msg_abc123xyz789",
    "status": "delivered",
    "phoneNumber": "+40712345678",
    "message": "Hello from SMSTunnel!",
    "deviceId": "dev_xyz",
    "createdAt": "2025-01-02T10:30:00Z",
    "sentAt": "2025-01-02T10:30:02Z",
    "deliveredAt": "2025-01-02T10:30:05Z"
  }
}

Status Values

• queued - Waiting to be sent
• sending - Being sent by device
• sent - Sent by device
• delivered - Confirmed delivered
• failed - Delivery failed

List all registered devices for your account.

Response

{
  "success": true,
  "data": [
    {
      "deviceId": "dev_abc123",
      "name": "Samsung Galaxy S21",
      "status": "online",
      "lastSeen": "2025-01-02T10:30:00Z",
      "smsToday": 45,
      "simInfo": {
        "carrier": "Vodafone",
        "countryCode": "RO"
      }
    }
  ]
}

Get detailed status of a specific device.

Response Fields

• status: online, offline, busy
• battery: Battery level percentage
• signal: Cellular signal strength
• queueLength: Messages waiting to be sent

Get your current usage statistics and limits.

Response

{
  "success": true,
  "data": {
    "plan": "standard",
    "billing": {
      "currentPeriodStart": "2025-01-01",
      "currentPeriodEnd": "2025-01-31"
    },
    "usage": {
      "smsToday": 150,
      "smsThisMonth": 2450,
      "2faToday": 89
    },
    "limits": {
      "smsPerDay": 1000,
      "2faPerDay": -1,
      "devices": 3
    }
  }
}

Configure webhooks to receive real-time delivery notifications (Pro plan).

Webhook Events

• sms.sent - Message sent by device
• sms.delivered - Delivery confirmed
• sms.failed - Delivery failed
• device.online - Device came online
• device.offline - Device went offline

Webhook Payload

POST /your-webhook-endpoint
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...

{
  "event": "sms.delivered",
  "timestamp": "2025-01-02T10:30:05Z",
  "data": {
    "messageId": "msg_abc123",
    "phoneNumber": "+40712345678",
    "status": "delivered"
  }
}

Verifying Signatures

Verify webhook authenticity by computing HMAC-SHA256 of the raw body with your webhook secret.