Quick start

Use a server access key from your account settings. Never expose this key in frontend code.

curl \
  --request GET \
  --url "https://app.aharon.cloud/api/v1/messages" \
  --header "Authorization: Bearer ACCESS_KEY_HERE" \
  --header "Accept: application/json"

Authentication

Header	`Authorization`
Value	`Bearer ACCESS_KEY_HERE`
Token type	`server`
Failure	`401 missing_bearer_token` / `401 invalid_token`

Response model

Success

{
  "ok": true
}

Error

{
  "ok": false,
  "error": "invalid_token",
  "message": "Bad request"
}

Status	Error	Meaning
400	`bad_request`, `missing_sender`	Invalid input or missing field.
401	`missing_bearer_token`, `invalid_token`	Token is missing, revoked or invalid.
402	`insufficient_credits`	Not enough sending credits.
423	`sms_sending_closed_weekend`	Sending is closed in the configured weekend window.
429	`too_many_recipients`	Too many recipients or rate limit.
502	`provider_send_failed`	SMS provider returned a failure.
503	`sms_sending_not_enabled`	Sending is disabled.

GET

/me

Returns the authenticated account and current SMS credit balance.

{
  "ok": true,
  "user": {
    "id": 123,
    "email": "customer@example.com",
    "token_id": 77,
    "token_type": "server",
    "sms_credits": 1000
  }
}

GET

/numbers

Lists virtual numbers assigned to the authenticated account.

{
  "ok": true,
  "numbers": [
    {
      "id": 12,
      "number_raw": "0500000000",
      "label": "Main",
      "status": "assigned"
    }
  ]
}

GET

/messages

Returns the latest 100 inbound messages, newest first.

Field	Type	Description
`id`	number	Message id.
`virtual_number_id`	number	Receiving number id.
`from_raw`	string	Original sender.
`to_raw`	string	Destination number.
`body`	string	Message body.
`provider_received_at`	datetime	Provider timestamp.

{
  "ok": true,
  "messages": [
    {
      "id": 991,
      "virtual_number_id": 12,
      "from_raw": "Google",
      "from_normalized": "Google",
      "from_type": "text",
      "to_raw": "0500000000",
      "body": "Your code is 123456",
      "provider_received_at": "2026-07-05 13:45:00",
      "first_seen_at": "2026-07-05 13:45:02"
    }
  ]
}

GET

/messages/{id}

Returns one inbound message by id if it belongs to the authenticated account.

Path	`id` — required message id.

{
  "ok": true,
  "message": {
    "id": 991,
    "virtual_number_id": 12,
    "from_raw": "Google",
    "body": "Your code is 123456"
  }
}

{
  "ok": false,
  "error": "not_found"
}

GET

/sms/credits

Returns the current outbound SMS credit balance.

{
  "ok": true,
  "sms_credits": 1000
}

POST

/senders/state

Marks a sender as spam or blocked.

Body	Required	Notes
`sender` / `from`	Yes	Sender identifier.
`state`	No	`spam` / `blocked`
`virtual_number_id`	No	Optional number scope.

{
  "sender": "0520000000",
  "state": "spam",
  "virtual_number_id": 12
}

{
  "ok": true,
  "result": {
    "state": "spam"
  }
}

POST

/senders/block

Shortcut endpoint for blocking a sender.

{
  "sender": "0520000000",
  "virtual_number_id": 12
}

{
  "ok": true,
  "blocked": true,
  "result": {
    "state": "blocked"
  }
}

POST

/sms/send

Sends SMS from an assigned virtual number. Billing is calculated by recipients and message segments.

Body	Required	Notes
`from`	Yes	Assigned sender number.
`message`	Yes	SMS text.
`phones` / `to`	Yes	Recipients separated by colon, comma or newline.
`flash`	No	Boolean alias: flash/sendFlashMessage/send_flash.

curl \
  --request POST \
  --url "https://app.aharon.cloud/api/v1/sms/send" \
  --header "Authorization: Bearer ACCESS_KEY_HERE" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "0500000000",
    "to": "0520000000",
    "message": "Your code is 123456"
  }'

{
  "ok": true,
  "sms": {
    "outbound_message_id": 456,
    "provider_status": "OK",
    "recipients_count": 1,
    "segments": 1,
    "credits_used": 1,
    "balance_after": 999,
    "flash": false
  }
}

Webhook

Configure a public HTTPS endpoint per number to receive incoming SMS events.

{
  "event": "sms.received",
  "to": "0500000000",
  "from": "Google",
  "body": "Your code is 123456",
  "received_at": "2026-07-05 13:45:00"
}

X-SMS-Timestamp: 1782395100
X-SMS-Signature: sha256=...
HMAC_SHA256(webhook_secret, timestamp + "." + rawBody)

Examples

curl

curl \
  --request GET \
  --url "https://app.aharon.cloud/api/v1/messages" \
  --header "Authorization: Bearer ACCESS_KEY_HERE" \
  --header "Accept: application/json"

Node.js

const response = await fetch('https://app.aharon.cloud/api/v1/messages', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer ACCESS_KEY_HERE',
    Accept: 'application/json'
  }
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.get(
    'https://app.aharon.cloud/api/v1/messages',
    headers={
        'Authorization': 'Bearer ACCESS_KEY_HERE',
        'Accept': 'application/json'
    },
    timeout=20
)

print(response.json())