Blog

Send SMS from a bash script with curl, and text yourself when a server needs you

One curl command sends a text from your own phone. Then the safe way to build the JSON, waiting for delivery, retries that can't double-text, and a cron job that texts you once an hour while the disk is full.

Sparetext

7 min read · Nov 11, 2026 · Updated Nov 18, 2026

Plenty of servers have that one cron job that emails someone when the disk fills up. The email lands in a folder nobody reads, and you find out from a customer. A text gets read. And if it comes from your own phone, there's no SMS account to set up for one alert a month.

Sparetext turns the Android phone you already own into an SMS gateway with a plain HTTP API, so curl is all a server needs. The text goes out from your phone, on your number. Every command below ran on 11 November against a test copy of Sparetext with a simulated phone on the other end. (On a Mac and want texts from your iPhone's number instead? The Mac terminal guide has a command-line tool for that.)

What you need

  • A Sparetext account. Free is 1 phone and 300 texts a month, which is a lot of alerts.
  • An Android phone with the Sparetext app, paired in the dashboard. An iPhone works too, through Sparetext for Mac (the iPhone guide).
  • An API key from the API keys page: export SPARETEXT_API_KEY=spt_live_.... For a server, make a key just for it, with a daily limit, so a runaway script can't spend your month.
  • curl, and jq for anything past the first command (apt install jq, brew install jq).

We ran everything on a Mac, and a Linux server has the same bash, curl and jq. Two commands differ: date, which the replies section handles, and uuidgen, which minimal Linux images often leave out. On those, cat /proc/sys/kernel/random/uuid prints one too.

Send your first text

bash
curl --fail-with-body -sS --max-time 15 https://sparetext.dev/api/v1/messages \
  -H "x-api-key: $SPARETEXT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"to":"+12025550181","text":"Backup finished on db-1."}'

Put your own number in to, with its country code. You get back JSON with a batchId and the message, whose status starts at queued, and your phone sends the text a moment later.

The flags earn their place. --fail-with-body makes curl exit with an error on a 4xx or 5xx but still print the answer, so a script notices failures and you can still read why. With a bad key our test printed curl: (22) The requested URL returned error: 401, then {"error":{"code":"unauthorized","message":"That key or token is not valid. It may have been revoked."}}, and exited with 22. -sS hides the progress bar but keeps errors. --max-time stops a stuck connection from hanging your script.

Build the JSON with jq, not by hand

Here's the thing about gluing variables into JSON in bash: the day your message has a quote in it, the JSON breaks. A deploy message like Deploy of "api" finished. It's live. would wreck a hand-built string twice over. jq -n builds the JSON and escapes everything for you, and -d @- makes curl read it from the pipe:

bash
TO="+12025550182"
TEXT='Deploy of "api" finished. It'\''s live.'

jq -n --arg to "$TO" --arg text "$TEXT" '{to: $to, text: $text}' |
  curl --fail-with-body -sS --max-time 15 https://sparetext.dev/api/v1/messages \
    -H "x-api-key: $SPARETEXT_API_KEY" -H "content-type: application/json" -d @- |
  jq '{status: .messages[0].status, id: .messages[0].id}'

That one came back queued with its id, quotes and apostrophe intact.

Wait until it's delivered

queued means the text is waiting for your phone. It then moves to dispatched (the phone has it), sent, and delivered if your carrier sends delivery reports. A text that goes wrong ends at failed. This script sends one and waits up to two minutes for the outcome:

status.sh
#!/usr/bin/env bash
set -euo pipefail
API="https://sparetext.dev/api/v1"

id=$(jq -n --arg to "+12025550111" --arg text "Your order #1042 is out for delivery." '{to: $to, text: $text}' |
  curl --fail-with-body -sS --max-time 15 "$API/messages" \
    -H "x-api-key: $SPARETEXT_API_KEY" -H "content-type: application/json" -d @- |
  jq -r '.messages[0].id')
echo "queued $id"

for _ in $(seq 40); do
  status=$(curl --fail-with-body -sS --max-time 15 "$API/messages/$id" \
    -H "x-api-key: $SPARETEXT_API_KEY" | jq -r '.message.status')
  case "$status" in
    delivered|failed|canceled) break ;;
  esac
  sleep 3
done
echo "$status"

Against the simulated phone it printed delivered after one check, about three seconds in. A real phone on a real network takes longer, and some carriers never send a delivery report, so a text can rest at sent. That's why the loop stops after 40 tries.

Retry safely: --retry plus an Idempotency-Key

--retry 4 makes curl try again after a timeout or an HTTP 408, 429, 500, 502, 503 or 504, and since curl 7.66 it obeys the Retry-After header the API sends with a 429. An account can make 15 send requests every 5 seconds. We sent 20 texts in a loop with --retry 4: one request was told to wait, curl waited, and all 20 came back 202 within 4 seconds.

But a retry after a timeout has a catch: maybe the first request did get through, and now the person gets the text twice. Add an Idempotency-Key header, and the API hands back the first answer instead of sending again. curl sends the same headers on every retry, so the two flags fit together nicely:

bash
jq -n --arg to "$TO" --arg text "$TEXT" '{to: $to, text: $text}' |
  curl --fail-with-body -sS --max-time 15 --retry 4 \
    -H "x-api-key: $SPARETEXT_API_KEY" -H "content-type: application/json" \
    -H "idempotency-key: $(uuidgen)" \
    -d @- https://sparetext.dev/api/v1/messages

Keys are kept for 24 hours. The same key with the same JSON gets the first answer back; the same key with different JSON gets 422 idempotency_mismatch, which we saw too. Don't use --retry-all-errors here: it would also retry a 401 or a bad number, which will never work.

A cron job that texts you when the disk is full

Now the useful part. This script checks the root disk and texts you when it's 90% full. The trick is the idempotency key: it's the host name plus the current hour, and the text doesn't change while the disk stays full. So cron can run it every five minutes, and you get one text an hour, not twelve:

disk-alert.sh
#!/usr/bin/env bash
# Texts you when the disk is nearly full. Run it from cron every 5 minutes.
set -euo pipefail

LIMIT=90
used=$(df -P / | awk 'NR == 2 { sub("%", "", $5); print $5 }')
[ "$used" -lt "$LIMIT" ] && exit 0

jq -n --arg to "$ALERT_TO" --arg text "$(hostname -s): disk / is over $LIMIT% full" \
  '{to: $to, text: $text}' |
curl --fail-with-body -sS --max-time 15 --retry 4 -o /dev/null \
  -H "x-api-key: $SPARETEXT_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: disk-$(hostname -s)-$(date +%Y%m%d%H)" \
  -d @- https://sparetext.dev/api/v1/messages

We tested it with the limit set to 1% so it would fire, and ran it three times in a row: three clean exits, one text. Then it bit us, which is worth knowing. Our first version put the exact percentage in the text. Run it again within the hour with a different number, and the key matches but the body doesn't, so the API answers 422 and the script exits with an error. That's why the text says "over 90%" and not "91%".

To install it, save it as /usr/local/bin/disk-alert.sh, make it executable, and add a line with crontab -e:

crontab
PATH=/usr/local/bin:/usr/bin:/bin
SPARETEXT_API_KEY=spt_live_...
ALERT_TO=+12025550114
*/5 * * * * /usr/local/bin/disk-alert.sh

Cron runs with a tiny PATH, so the first line makes sure it finds jq and curl. If the key in your crontab bothers you, keep it in a file only that user can read and source it at the top of the script instead. The same pattern works for any check that returns yes or no: a backup that didn't finish, a certificate that expires in a week, a site that stopped answering. (If you already watch your sites with Uptime Kuma, its webhook can text you with no script at all.)

Read the replies

Replies land in the same API. This prints what came in over the last ten minutes. date is the annoying part, because macOS and Linux spell "ten minutes ago" differently, so it tries both:

bash
since=$(date -u -v-10M +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '10 minutes ago' +%Y-%m-%dT%H:%M:%SZ)

curl --fail-with-body -sS --max-time 15 -G https://sparetext.dev/api/v1/messages \
  -H "x-api-key: $SPARETEXT_API_KEY" \
  --data-urlencode "direction=inbound" --data-urlencode "since=$since" |
  jq -r '.messages[] | "\(.contact) said: \(.text)"'

We texted a test number asking it to reply YES, and the command printed +12025550115 said: YES. For a bot that answers within seconds, have Sparetext call a URL instead: the webhook guide shows how.

What this can't do

A phone is the right tool for texts to people who know you, and alerts to yourself and your team are the easiest case of all. It's the wrong tool for marketing to a list that didn't ask: carriers filter business texts sent by software even from a personal number (the 10DLC post explains). An iPhone can't send silently in the background the way Android can, and only Android phones get carrier delivery reports. Free covers 300 texts a month and Pro 10,000 on up to 5 phones (pricing).

When the alert turns into an app, the same steps exist for Python, Node.js, Go, PHP, Ruby and Java.

Try it with your own number

Make a key on the API keys page, pair your phone, and paste the first command with your own number in to. When your pocket buzzes, drop disk-alert.sh on the server you worry about most.

The everyday commands are also in our public examples repo, ready to copy: sparetext-examples/curl sends, checks a status, reads replies, polls for new texts, texts a list and sends one-time codes.

bashlinuxcurlcommand linesend smscronserver alertstutorial

Try it with the phone you have

Free for 1 phone and 300 texts a month. Pair it in about two minutes.

Start free

Responses

Sign in or create an account to respond.

More from the blog