Send SMS with cURL

cURL is the quickest way to try the API and to send SMS from shell scripts and cron jobs. -G turns the data into a GET query string and --data-urlencode takes care of spaces and special characters in the message.

Send an SMS

curl -G "https://api.budgetsms.net/sendsms/" \
  --data-urlencode "username=USERNAME" \
  --data-urlencode "userid=USERID" \
  --data-urlencode "handle=HANDLE" \
  --data-urlencode "from=BudgetSMS" \
  --data-urlencode "to=31612345678" \
  --data-urlencode "msg=Hello from BudgetSMS"

The response is one line. On success it is OK followed by the message id, which you keep for the delivery report:

OK 64354593

On failure it is ERR followed by an error code, for example ERR 1001 when the credit is exhausted or ERR 2004 for an invalid sender ID. The HTTP status is always 200, so look at the first word, not at the status code.

Test without sending

Replace sendsms with testsms. The call checks your credentials and answers in the same format as a real send, but it is a simulator: no SMS is sent and nothing is charged, the message id and price are random, and about one in five calls returns a random ERR 2xxx so you can test your error handling. The destination number is not checked; real prices come from /getpricing/.

curl -G "https://api.budgetsms.net/testsms/" \
  --data-urlencode "username=USERNAME" --data-urlencode "userid=USERID" --data-urlencode "handle=HANDLE" \
  --data-urlencode "from=BudgetSMS" --data-urlencode "to=31612345678" --data-urlencode "msg=Test" \
  --data-urlencode "price=1" --data-urlencode "mccmnc=1" --data-urlencode "credit=1"

With price=1, mccmnc=1 and credit=1 the response also contains the price and the number of SMS parts, the network of the receiver and your remaining credit:

OK 64354593 0.0640 1 20408 123.4550

Check your credit

curl -G "https://api.budgetsms.net/checkcredit/" \
  --data-urlencode "username=USERNAME" --data-urlencode "userid=USERID" --data-urlencode "handle=HANDLE"
# OK 123.4550

Look up a number (network and portability)

curl -G "https://api.budgetsms.net/np/" \
  --data-urlencode "username=USERNAME" --data-urlencode "userid=USERID" --data-urlencode "handle=HANDLE" \
  --data-urlencode "to=31612345678"
# OK 204 08 0.0640   (MCC, MNC of the current network, and your SMS price to that network)

NP tells you the network a number belongs to today, also after porting; HLR (replace np with hlr) also tells whether the handset is reachable.

Delivery status of a message

curl -G "https://api.budgetsms.net/checksms/" \
  --data-urlencode "username=USERNAME" --data-urlencode "userid=USERID" --data-urlencode "handle=HANDLE" \
  --data-urlencode "smsid=64354593"
# OK 1   (1 = delivered; see the DLR status list for the other codes)

For anything beyond a quick check, use Push DLR: we call your URL on every status change, so you never have to poll.

Your prices as JSON

curl -G "https://api.budgetsms.net/getpricing/" \
  --data-urlencode "username=USERNAME" --data-urlencode "userid=USERID" --data-urlencode "handle=HANDLE" | jq .

The result is an object keyed by operator id with the country, operator, MCC, MNC and your price per SMS part; see Account pricing.