Send SMS with curl from your own phone.
To send an SMS with curl, POST number and message to https://app.sms8.io/api/v1/messages with your API key in the X-Api-Key header. One command, and the text leaves from the SIM in your own Android phone. Use it to test the API, in shell scripts, cron jobs and CI.
Quick start in three steps
From a new account to a delivered text in a few minutes.
Get your API key
Create an SMS8 account, pair an Android phone with the SMS8 app, and copy your key from the API page of the dashboard.
Export it
Run export SMS8_API_KEY=your_key in your shell so the key stays out of your command history and scripts.
Send your first SMS
Paste the command below with your own number. The phone you paired sends the text from its SIM, and the answer shows the message ID.
How do I send an SMS with curl?
export SMS8_API_KEY=your_key
curl -X POST https://app.sms8.io/api/v1/messages \
-H "X-Api-Key: $SMS8_API_KEY" \
--data-urlencode "number=+14155550100" \
--data-urlencode "message=Hello from curl and SMS8"
Use --data-urlencode so the + in the number and any spaces or symbols in the text arrive intact. A success looks like this, trimmed:
{
"success": true,
"data": { "messages": [ { "ID": 128476, "number": "+14155550100", ... } ] },
"error": null
}
A refusal keeps the same shape, with success false and an error object holding a code and a message. Pipe the answer to jq to pull the ID:
curl -s -X POST https://app.sms8.io/api/v1/messages \
-H "X-Api-Key: $SMS8_API_KEY" \
--data-urlencode "number=+14155550100" \
--data-urlencode "message=Backup finished" | jq '.data.messages[0].ID'
How do I send SMS to many numbers with curl?
For the same text, put the numbers comma-separated in number. Add option=1 to rotate across every phone you paired, or option=2 to rotate across every SIM.
curl -X POST https://app.sms8.io/api/v1/messages \
-H "X-Api-Key: $SMS8_API_KEY" \
--data-urlencode "number=+14155550100,+14155550101,+14155550102" \
--data-urlencode "message=The store opens at 9:00 tomorrow." \
-d "option=1"
For a different text per person, send a messages field holding a JSON list:
curl -X POST https://app.sms8.io/api/v1/messages \
-H "X-Api-Key: $SMS8_API_KEY" \
--data-urlencode 'messages=[
{"number":"+14155550100","message":"Hi Ana, your table for 4 is ready."},
{"number":"+14155550101","message":"Hi Ben, your order #4412 has shipped."}
]'
Add -d "schedule=$(( $(date +%s) + 3600 ))" to send in one hour, or -d "prioritize=1" for alerts that must go first. The API has no artificial rate limit, but each SIM should send about one message every 10 to 30 seconds; add phones to send more.
How do I send an MMS with curl?
Set type=mms and put public image links in attachments, separated by commas. JPG, PNG, GIF and WEBP work, and SMS8 resizes each image to 1,280 pixels.
curl -X POST https://app.sms8.io/api/v1/messages \
-H "X-Api-Key: $SMS8_API_KEY" \
--data-urlencode "number=+14155550100" \
--data-urlencode "message=Here is your receipt." \
-d "type=mms" \
--data-urlencode "attachments=https://example.com/receipt.jpg,https://example.com/map.png"
More in the guide on sending MMS through an API.
How do I check my phones before a big send?
curl -H "X-Api-Key: $SMS8_API_KEY" https://app.sms8.io/api/v1/devices
The answer lists each paired phone with its battery, signal, SIMs and last seen time, and the device IDs you can pass in devices to pick the sender.
How do I read SMS replies with curl?
Ask the read endpoint for messages received since a time. This one covers the last hour:
curl -s -X POST https://app.sms8.io/api/v1/messages/read \
-H "X-Api-Key: $SMS8_API_KEY" \
-d "status=Received" \
-d "startTimestamp=$(( $(date +%s) - 3600 ))" \
-d "limit=100" | jq '.data.messages[] | {number, message}'
When nothing matches, the answer is success: false with error code 404, which simply means an empty inbox. You can also filter by id, deviceID, simSlot or endTimestamp, and page with limit and offset.
Check a webhook signature from the shell
For a live app, add an HTTPS URL on the Webhooks page of the dashboard and subscribe it to received messages. Each request carries an X-Signature header: sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with that webhook's own signing secret. To check a captured request by hand, save the raw body to a file and run:
printf 'sha256=%s\n' "$(openssl dgst -sha256 -hmac "$SMS8_WEBHOOK_SECRET" -r body.json | cut -d' ' -f1)"
The output must equal the X-Signature header exactly. In your server code, compare the two with a constant-time function; the Python, Node.js, PHP and C# pages each show a ready receiver. When to use which approach is in webhook vs polling for incoming SMS.
Errors and retries
| What you see | Meaning | What to do |
|---|---|---|
| Error code 401 | Missing or wrong API key | Fix the key. Do not retry |
| Error code 400 | Missing or malformed fields | Fix the request. Do not retry |
success: false with a message | Refused, for example no credits left | Log and alert. Retrying will not help |
| Error code 404 on a read | No messages match | Treat as an empty list |
| Error code 500, HTTP 5xx or a timeout | Temporary problem | Retry with backoff |
In scripts, retry on network failures only, and pass an idempotencyKey so a retry never becomes a second text. SMS8 also returns the first answer for an identical request repeated within five minutes.
curl -sS --retry 3 --retry-connrefused --max-time 30 \
-X POST https://app.sms8.io/api/v1/messages \
-H "X-Api-Key: $SMS8_API_KEY" \
--data-urlencode "number=+14155550100" \
--data-urlencode "message=Nightly backup failed on db-1" \
-d "idempotencyKey=backup-db-1-$(date +%F)" | jq -e '.success' > /dev/null \
|| echo "SMS8 refused the message" >&2
jq -e exits non-zero when success is false, so your script can stop or alert. If the phone later reports a message as failed, put the original back in the queue by its ID instead of sending a new copy:
curl -X POST https://app.sms8.io/api/v1/messages/resend \
-H "X-Api-Key: $SMS8_API_KEY" \
-d "id=128476"
Prefer a dedicated tool? npm install -g sms8-sdk gives you the sms8 command, covered in send SMS from the terminal. Every field is in the SMS8 API documentation, and the SMS API guide for developers covers pacing and bulk sends.
Why choose SMS8
An SMS API without a number to rent or a meter to watch.
One command to send
A single POST with a header and two fields. Easy to test, easy to drop into cron, CI or a monitoring alert.
Your own number
Texts leave from the SIM in your own Android phone, so people see a number they know and can reply to it.
Flat price, unlimited messages
USD 29 a month for one phone, USD 89 for five and USD 229 for twenty, with unlimited SMS and MMS and no per-message fee. Yearly billing is half the price.
No A2P 10DLC filing
Texts go person-to-person from your SIM, so there is no brand or campaign registration to wait for.
CLI and MCP included
npm install sms8-sdk adds the sms8 command, and the MCP server at mcp.sms8.io lets Claude and Cursor send from your number.
Setup in minutes, with a trial
Pair a phone, copy a key and send. The 3-day trial includes 30 messages and needs no card.
Keep going
The reference, the guides and the same examples in other languages.
SMS8 API documentation
Every endpoint, field and webhook event in one place.
Open the docsSMS API guide for developers
Sending, receiving, signatures, retries and pacing, with code in four languages.
Read the guideWebhook vs polling
Which way to receive incoming SMS, and a clean polling loop when you need one.
Read the articleSend SMS with Python
requests and a Flask webhook.
Python examplesSend SMS with Node.js
The sms8-sdk package from npm, plus plain fetch.
Node.js examplesSend SMS with PHP
curl, hash_hmac and a ready PHP class.
PHP examplesSend SMS with C#
HttpClient and an ASP.NET Core webhook.
C# examplesExport your SMS8 key, then POST number and message to https://app.sms8.io/api/v1/messages with the X-Api-Key header and --data-urlencode. The JSON answer shows success and the message ID.
A plain + in form data is read as a space. --data-urlencode encodes it, along with spaces and symbols in your text, so the number and message arrive exactly as you typed them.
Yes. Put the curl command in your script, keep the key in an environment variable or a CI secret, and check the success flag with jq -e so a refusal fails the step.
Start the SMS8 trial: 3 days and 30 messages with no card. After that, a flat plan from USD 29 a month covers unlimited SMS and MMS from your own phone.
Yes. X-Api-Key is the standard header. An Authorization Bearer header or a form field called key also work, for tools that cannot set custom headers.
Send your first SMS with curl
Pair a phone, export your API key and paste one command. 3-day trial with 30 messages, no card needed.