---
name: simplesms
description: Send and receive SMS, verify phone numbers with one-time codes, and provision US/Canada phone numbers through the SimpleSMS API. Use when a task needs to send a text message, get a phone number, or verify/look up a phone number.
---

# SimpleSMS

SimpleSMS is an SMS API for developers: two-way texting, on-demand phone numbers,
backed by the infrastructure of the consumer phone app.

## Setup

Official SDK (Node 18+, zero dependencies): `npm install joinsimplesms`

```js
import { SimpleSMS } from 'joinsimplesms';
const sms = new SimpleSMS(process.env.SIMPLESMS_API_KEY);
await sms.verify.send({ to: '+14155550132' });
const { verified } = await sms.verify.check({ to: '+14155550132', code });
```

Raw HTTP works too; everything below is the same API.

1. Get a free sandbox key (instant, no card): https://joinsimplesms.com/console
2. Every request: `Authorization: Bearer ssms_sk_test_...`
3. Base URL: `https://api.joinsimplesms.com/v1`

Test keys simulate everything (magic numbers: `+15005550006` delivers,
`+15005550002` fails, `+15005550001` sticks in queued). The one exception: the
developer's own phone, verified once in the console, gets real delivery from a
test key (10/day). Live keys are enabled
after live-access review from the console.

## Send an SMS

```bash
curl -X POST https://api.joinsimplesms.com/v1/messages \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "<your number>", "to": "+15005550006", "body": "Hello"}'
```

Your numbers: `GET /v1/numbers`. Response has `id` (msg_...) and `status`
(`queued|sent|delivered|failed`). Retries are safe with an `Idempotency-Key`
header.

## Phone verification (OTP): use the `simplesms-verify` skill

For OTP / 2FA / phone verification, use `POST /v1/verify` +
`POST /v1/verify/check`; never `messages.send()` with a code you generated.
No number purchase is needed; SimpleSMS sends from its own pool, and billing is
only on a successful check. Full rules, sandbox codes, and UI guidance live in
the dedicated skill:
https://joinsimplesms.com/skills/simplesms-verify/SKILL.md

## Get a phone number

```bash
curl "https://api.joinsimplesms.com/v1/numbers/available?area_code=415" -H "Authorization: Bearer $SIMPLESMS_API_KEY"
curl -X POST https://api.joinsimplesms.com/v1/numbers -H "Authorization: Bearer $SIMPLESMS_API_KEY" \
  -H "Content-Type: application/json" -d '{"phone_number": "<from search>"}'
```

## Look up a number

```bash
curl "https://api.joinsimplesms.com/v1/lookup/+14155550132" -H "Authorization: Bearer $SIMPLESMS_API_KEY"   # carrier, line type
```

## Inbound + events

- Simulate inbound in sandbox: `POST /v1/test/inbound {to, from, body}`
- Poll `GET /v1/events` for `message.sent|delivered|failed|received`.

## References

- Full docs (single file): https://joinsimplesms.com/docs/llms-full.txt
- OpenAPI: https://joinsimplesms.com/api/v1/openapi.yaml
- MCP server (same tools, tool-call form): https://joinsimplesms.com/api/mcp
- Errors are always `{"error": {"code", "message"}}`; see https://joinsimplesms.com/docs/errors.md