[Blog](https://sparetext.dev/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](https://sparetext.dev/send-sms-from-mac-terminal) 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](https://sparetext.dev/iphone-sms-gateway)).
- 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

```bash
#!/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.

We learned this the fun way: our first run sat at `queued` forever. That test number had texted an old, switched-off simulated phone the week before, and a text goes from the phone a person last texted with. With two phones paired, add `"deviceId"` to the JSON to pick one yourself.

## 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

```bash
#!/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](https://sparetext.dev/blog/uptime-kuma-sms-alerts) 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](https://sparetext.dev/receive-sms-webhook) 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](https://sparetext.dev/blog/send-sms-without-10dlc) 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](https://sparetext.dev/pricing)).

When the alert turns into an app, the same steps exist for [Python](https://sparetext.dev/blog/send-sms-from-python), [Node.js](https://sparetext.dev/blog/send-sms-from-node-js), [Go](https://sparetext.dev/blog/send-sms-from-go), [PHP](https://sparetext.dev/blog/send-sms-from-php), [Ruby](https://sparetext.dev/blog/send-sms-from-ruby) and [Java](https://sparetext.dev/blog/send-sms-from-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](https://github.com/eliasayele/sparetext-examples/tree/main/curl) sends, checks a status, reads replies, polls for new texts, texts a list and sends one-time codes.

bash linux curl command line send sms cron server alerts tutorial

Try it with the phone you have

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

[Start free](https://sparetext.dev/signup)

## Responses

[Sign in](https://sparetext.dev/login?next=%2Fblog%2Fsend-sms-from-bash-with-curl%23responses) or [create an account](https://sparetext.dev/signup?next=%2Fblog%2Fsend-sms-from-bash-with-curl%23responses) to respond.

## More from the blog

- **[Your first text from code in five minutes, timed against Twilio's steps](https://sparetext.dev/blog/first-text-from-code-in-five-minutes)**
   5 min read
- **[Uptime Kuma SMS alerts from your own phone, with one webhook](https://sparetext.dev/blog/uptime-kuma-sms-alerts)**
   6 min read
- **[We handed our dashboard to two AI agents: this week in Sparetext](https://sparetext.dev/blog/we-handed-our-dashboard-to-two-ai-agents)**
   5 min read

---

This is the Markdown copy of https://sparetext.dev/blog/send-sms-from-bash-with-curl for AI agents. Every public page has one: add .md to its address (the home page is https://sparetext.dev/index.md). Sparetext for agents in one file: https://sparetext.dev/llms.txt
