Send SMS with Node.js from your own phone.
To send an SMS from Node.js, install sms8-sdk from npm and call sendSMS with a phone number and a message, or POST the same fields to https://app.sms8.io/api/v1/messages with fetch. The text leaves from the SIM in your own Android phone, with no per-message fee and no A2P 10DLC filing.
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. Store it in an environment variable called SMS8_API_KEY.
Install sms8-sdk
Run npm install sms8-sdk. One package gives you the SDK, the sms8 command line tool, React OTP helpers and an MCP bridge. It works in Node 18 and newer, Bun, Deno and edge runtimes.
Send your first SMS
Call sendSMS with your own number. The phone you paired sends the text from its SIM, and you get a message ID back.
How do I send an SMS with Node.js?
npm install sms8-sdk
import { Sms8 } from 'sms8-sdk';
const sms8 = new Sms8({ apiKey: process.env.SMS8_API_KEY });
const res = await sms8.sendSMS({
phone: '+14155550100',
message: 'Hello from Node.js and SMS8',
});
if (res.success) console.log('queued as', res.messageId);
else console.error('refused:', res.error);
The result has success, messageId, phone and error. Routing options go in the same object: deviceId and simSlot to pick the sender, option (0 for the listed device, 1 to rotate across phones, 2 to rotate across SIMs), randomDevice and prioritize to jump the queue.
Prefer no dependency? The REST call is one fetch:
const r = await fetch('https://app.sms8.io/api/v1/messages', {
method: 'POST',
headers: { 'X-Api-Key': process.env.SMS8_API_KEY },
body: new URLSearchParams({ number: '+14155550100', message: 'Hello from fetch' }),
});
const body = await r.json();
if (body.success) console.log('queued as', body.data.messages[0].ID);
else console.error(body.error.code, body.error.message);
Keep the key on the server. Never put it in a browser bundle; call SMS8 from an API route, a server action or a worker.
How do I send SMS to many numbers in Node.js?
With the REST API, put the numbers comma-separated in number for the same text, and add option=1 to rotate across every phone you paired:
const numbers = ['+14155550100', '+14155550101', '+14155550102'];
const r = await fetch('https://app.sms8.io/api/v1/messages', {
method: 'POST',
headers: { 'X-Api-Key': process.env.SMS8_API_KEY },
body: new URLSearchParams({
number: numbers.join(','),
message: 'The store opens at 9:00 tomorrow.',
option: '1',
}),
});
const ids = (await r.json()).data.messages.map((m) => m.ID);
For a different text per person, send a messages field with a JSON list:
const batch = [
{ number: '+14155550100', message: 'Hi Ana, your table for 4 is ready.' },
{ number: '+14155550101', message: 'Hi Ben, your order #4412 has shipped.' },
];
await fetch('https://app.sms8.io/api/v1/messages', {
method: 'POST',
headers: { 'X-Api-Key': process.env.SMS8_API_KEY },
body: new URLSearchParams({ messages: JSON.stringify(batch) }),
});
With the SDK, loop over your list and call sendSMS for each person, passing option: 1 to spread the load. Add schedule (a Unix timestamp) on the REST call to send later. 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 Node.js?
Pass public image links in attachments:
await sms8.sendSMS({
phone: '+14155550100',
message: 'Here is your receipt.',
attachments: ['https://example.com/receipt.jpg'],
});
Over REST, set type to mms and put the links in attachments, separated by commas. JPG, PNG, GIF and WEBP work, and SMS8 resizes each image to 1,280 pixels. More in the guide on sending MMS through an API.
How do I read SMS replies in Node.js?
For a script or a dashboard, read recent messages with the SDK:
const { messages } = await sms8.getMessages({ direction: 'received', limit: 20 });
for (const m of messages) console.log(m.number, m.message);
getMessages also takes phone to filter on one contact. The SDK also has listDevices() and getBalance() to check your phones and plan before a big send.
Receive replies with a signed webhook (Express)
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 signing secret. Hash the raw bytes, before JSON parsing, and compare in constant time.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/sms8/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.SMS8_WEBHOOK_SECRET)
.update(req.body)
.digest('hex');
const received = req.get('X-Signature') || '';
const ok = received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!ok) return res.sendStatus(401);
res.sendStatus(200); // answer fast
const event = JSON.parse(req.body.toString('utf8'));
for (const m of event.data ?? []) queue.push(m); // your code: dedupe on m.ID
});
app.listen(3000);
A received message arrives with event, timestamp, userID and a data list where each item has ID, number, message, deviceID and simSlot. Answer with a 2xx within 10 seconds. If your server is down, SMS8 retries on a growing schedule for up to 30 days, so store each ID with a unique index. The trade-offs are 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 |
With the SDK, check res.success, and wrap the call in try/catch: a network or HTTP failure throws. Over REST, retry only on timeouts and server errors, 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.
class Permanent extends Error {}
async function sendWithRetry(number, message, key, attempts = 4) {
for (let i = 0; i < attempts; i++) {
try {
const r = await fetch('https://app.sms8.io/api/v1/messages', {
method: 'POST',
headers: { 'X-Api-Key': process.env.SMS8_API_KEY },
body: new URLSearchParams({ number, message, idempotencyKey: key }),
signal: AbortSignal.timeout(30_000),
});
const body = await r.json();
if (body.success) return body.data.messages[0];
if (r.status < 500 && body.error?.code !== 500) throw new Permanent(body.error?.message);
} catch (e) {
if (e instanceof Permanent || i === attempts - 1) throw e;
}
await new Promise((res) => setTimeout(res, 2 ** i * 1000)); // 1s, 2s, 4s
}
throw new Error('SMS8 send failed after retries');
}
If the phone later reports a message as failed, put the original back in the queue with POST /api/v1/messages/resend and its id, instead of sending a new copy. Every field is in the SMS8 API documentation, and the SMS API guide for developers covers pacing and bulk sends in depth.
Why choose SMS8 for Node.js
An SMS API without a number to rent or a meter to watch.
One npm package
sms8-sdk bundles typed methods, the sms8 CLI, React OTP components and an MCP bridge for Claude and Cursor.
Your own number
Texts leave from the SIM in your own Android phone, so customers 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.
OTP built in
sendOTP and verifyOTP cover phone verification in two calls, from your own number, with no fee per code.
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 PHP
curl, hash_hmac and a ready PHP class.
PHP examplesSend SMS with C#
HttpClient and an ASP.NET Core webhook.
C# examplesSend SMS with curl
Test every endpoint from the terminal.
curl examplessms8-sdk. Install it with npm install sms8-sdk and import { Sms8 } from it. The same package ships the sms8 command line tool and an MCP bridge you start with npx -y sms8-sdk mcp.
Yes. sms8-sdk is written in TypeScript and runs in Node 18 and newer, Bun, Deno, Cloudflare Workers and Next.js server actions. Keep the API key on the server side.
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.
Register an HTTPS webhook on the dashboard, subscribe it to received messages and verify the X-Signature header with crypto.createHmac and timingSafeEqual. For scripts, call sms8.getMessages with direction received.
The API has no artificial limit. Each SIM should send about one message every 10 to 30 seconds, so add phones and rotate across them with option 1 or 2 for more volume.
Send your first SMS from Node.js
Run npm install sms8-sdk, pair a phone and call sendSMS. 3-day trial with 30 messages, no card needed.