To send an SMS with curl, POST a small JSON body to your provider's messages endpoint with your API key in a header. With Ready that's one command against https://api.tryready.com/v1/messages, and it works from any terminal with curl installed. It's also the fastest way to prove a key, a number and a registration are all wired up before you write real code.
We make Ready, so the examples use its API, and every request shape below is one we can vouch for. The habits carry over to any REST SMS API. Put the key in an environment variable, send an idempotency key, and read the status code before you trust the output.
Before you run anything
You need four things:
- An API key, sent in an
X-API-Keyheader. Export it once per shell session so it never lands in your shell history or a script:export READY_API_KEY="your-key". - A card on file and a number of your own. Ready requires both to send, from the first text. The number is $2 a month.
- A recipient who agreed to be texted. Your first test can go to your own phone.
- A plan for registration. An account can send up to 500 texts a month before it registers, at its normal per-text rate. Past that, registration is required. Most approvals take 2 to 7 days.
The one-line send
curl -X POST https://api.tryready.com/v1/messages \
-H "X-API-Key: $READY_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"to": "+12125550199", "body": "Your order #1042 has shipped.", "consent_attested": true}' Here's what each part does:
| Piece | What it's for |
|---|---|
-X POST | The messages endpoint takes a POST. |
X-API-Key header | Authenticates the request. A missing or wrong key is refused. |
Idempotency-Key header | Any UUID. A retry with the same key never sends a second text. |
to | The recipient in E.164 format. A 10-digit US number is treated as +1. |
body | The message text. Each segment is billed. |
consent_attested | Your promise that the recipient agreed to texts. |
Two optional fields are worth knowing. from picks one of your own numbers, and media_url sends a picture as MMS. If you leave from out, Ready picks the number: the one this contact already texts with, otherwise your number closest to their area code. That default keeps a conversation on a single number, which is usually what you want.
If you run the command on Windows PowerShell, curl can be an alias for a different command. Call curl.exe instead, and swap the shell variable syntax for PowerShell's. The shape of the request doesn't change.
Make a retry safe
The reason the example carries an Idempotency-Key is simple. A curl command can time out after the text has already gone out. If you press the up arrow and run it again with a new key, the customer may get the message twice.
Generate the key once, keep it, and reuse it:
KEY=$(uuidgen)
curl --max-time 30 -X POST https://api.tryready.com/v1/messages \
-H "X-API-Key: $READY_API_KEY" \
-H "Idempotency-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+12125550199", "body": "Your order #1042 has shipped.", "consent_attested": true}' --max-time 30 makes curl give up after 30 seconds instead of hanging. If that command times out, run the same command again. Same key, same text, and the API won't send it twice. When you script this in a cron job or a CI step, derive the key from something stable, such as an order id, instead of generating a fresh one on every run. Idempotency keys and duplicate texts explains where this goes wrong.
Read the response
By default curl prints only the body and hides the status code, which is how people miss failures. Two flags fix that. -i prints the response headers with the body, and -w can print just the status code:
curl --max-time 30 -s -o response.json -w "%{http_code}\n" -X POST https://api.tryready.com/v1/messages \
-H "X-API-Key: $READY_API_KEY" \
-H "Idempotency-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{"to": "+12125550199", "body": "Your order #1042 has shipped.", "consent_attested": true}' That writes the body to response.json and prints a status code you can branch on in a shell script. A 2xx means the request was accepted. Anything else, read response.json before you change anything. The error reference lists the codes, and SMS API error codes and troubleshooting turns them into fixes.
Some refusals are by design and not charged:
- Opted-out numbers. Ready refuses a number that replied STOP, and the refusal is final.
- Numbers on your Ban list, and numbers Ready's own sends have already seen as landlines.
- A quiet-hours hold. An API text is held only if the window opens within 6 hours. Otherwise it isn't sent and the API answers 409
QUIET_HOURS_BLOCK. Send"hold_until_allowed": trueand Ready holds it for up to 24 hours instead, charged only when it sends. Or schedule it for when the window opens:POST /sms/schedulewithsend_atset to the answer'snext_allowed_at.
Don't retry a refusal in a loop. It will fail the same way every time.
Send the same text to many numbers
POST /v1/messages/bulk takes to as an array. A single call holds at most 100 recipients, so a longer list needs batches.
curl -X POST https://api.tryready.com/v1/messages/bulk \
-H "X-API-Key: $READY_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"to": ["+12125550199", "+15559876543"], "body": "Our office opens at 10 tomorrow.", "consent_attested": true}' For a whole list in one request, with pacing and quiet-hours holds, import the numbers as contacts and use POST /campaigns instead; see the campaigns API. To stay on the bulk send with a file of numbers, split it with split -l 100 numbers.txt batch_, then build each JSON array from one batch file with jq. Give every batch its own key, and store that key next to the batch file so a rerun reuses it. The bulk SMS API guide and the bulk messages reference cover batching and response details.
What each curl send costs
Each segment bills at $0.0075 plus a $0.0045 carrier fee passed through at cost, which is $0.012 per segment all-in, not including screening. Screening is the Scrub lists and Number validation switches, each $0.003 extra per segment when switched on. Accounts opened before November 12, 2026 keep their signup prices, shown under Billing.
Ready's all-in prices per segment include the carrier fee but not screening: Scrub lists and Number validation, the two switches in Settings under Compliance, each add $0.003 per segment when switched on, shown as screening on your bill, and both are off by default. Unless you turn the opt-out footer off, the first text to each contact, and one again from time to time, also gets "Reply STOP to opt out" and your business name if the message does not already have them, so a text close to the segment limit can bill one more segment.
Segments are what count, not messages. A segment holds 160 GSM-7 characters, or 153 each once a text runs past one. One emoji drops the limit to 70 characters, 67 per segment on a longer text. So a 140-character text with one emoji is 3 segments, and a test loop that sends 200 of them bills 600 segments, not 200. Check your message length before you script a loop. The pricing page lists every price.
Keep PHI out of test texts and real ones. Ready isn't HIPAA compliant and doesn't sign BAAs.
Read your sent messages back
To check what went out, GET /v1/messages returns messages, and it pages with before_id:
curl -s https://api.tryready.com/v1/messages \
-H "X-API-Key: $READY_API_KEY" That's the command to run after a 504 or a timeout you can't explain. Look at the list before you resend, because the text may already have gone out. For replies as they arrive, set up a webhook instead of polling. The API quickstart walks through key, first send and webhook in order.
The practical takeaway
A working SMS send is one POST with three headers. The two habits that keep it safe are exporting the key instead of pasting it, and holding on to the idempotency key until you know the outcome. Once the command works, moving it into Node, Python, Java or C# is mostly translation. See Send SMS in Python for the same request in code. When you're ready to try it, sign up and run the first command against your own phone.