SMS API: what it is, what to look for, and how to send your first text

A text is not done when the API answers. It is accepted, then sent, then delivered, or it fails, and only the carrier knows which. You want a webhook for each step, signed so you can trust it, with a reason when a text fails: a landline, a number that no longer works, a message the carrier filtered. Rasket sends six SMS events, from sms.queued to sms.delivered and sms.failed, plus sms.received for replies and contact.sms_unsubscribed for opt-outs, signed the same way as its email webhooks (the SMS webhooks page has the payloads).

Networks drop responses. If your code times out and sends again, a careless API texts the person twice, and a second one-time code or a second “your order shipped” is confusing at best. Look for an Idempotency-Key header: the same key within a window returns the first answer instead of sending again. On POST /sms it holds for 24 hours, a replay carries Idempotent-Replayed: true, and the same key with a different body is refused with 409 invalid_idempotent_request, so a bug cannot reuse a key for a new text. The idempotent sends post shows the retry loop; it is the same for texts.

The provider should be careful on its side too. When a hand-off to the carrier times out, Rasket does not resubmit it, because a second submission could reach the phone twice. It waits for the carrier's late report instead, and marks the text failed, and unbilled, if none arrives within the hour.

US law treats a text like a call. Under the FCC's rules a marketing text sent with automated equipment needs the person's prior express written consent. A person may revoke consent by any reasonable means, a reply of STOP, QUIT, END, REVOKE, OPT OUT, CANCEL or UNSUBSCRIBE counts as one on its own, and the sender has at most ten business days to honour it. Canada's anti-spam law requires consent for commercial messages as well. An SMS API should keep that record for you and stop texts the moment someone opts out.

In Rasket, SMS consent is its own fact on the contact, recorded with where and how the person agreed and the words they saw, and kept as proof for five years. STOP and its synonyms stop every text from your project to that phone, transactional ones included; only the person can undo it, by texting START. HELP is answered for you with your business name and how to stop. Consent and STOP has the details.

The number a text comes from decides who it can reach and how long you wait before you can send. In the US and Canada there are three kinds:

Start with toll-free: it reaches both countries, and it is the only way to text people in Canada from an application. Registration usually takes 1 to 5 business days. While yours is in review you are not stuck: Rasket lets you text your own verified phones from its shared test number straight away, with [Test] in front, so you can build and test the whole flow before the approval comes back.

Carriers set how fast each registered number may send, and a local number's registration also carries a daily cap. An SMS API should queue your texts and pace them to the number's rate rather than fail the ones above it. Rasket queues every text per number and sends at that number's rate; a campaign that reaches a daily cap carries the rest to the next day instead of failing them. For a burst of transactional texts, POST /sms/batch takes up to 100 in one request.

• Destinations. +1 is not only the US and Canada: the Caribbean shares it. Rasket accepts US and Canadian mobile numbers and answers anything else, including toll-free and premium numbers, with 422 unsupported_destination.
• Who you are. Every text starts with your brand, “Acme: ”, added when the text does not already start with it. Canada's law asks every commercial message to identify the sender, and US carriers expect it.
• Marketing texts go out only between 8 am and 9 pm where the person is, or the shorter hours some states set, at most once in any 16 hours, and always end with “Reply STOP to opt out”. A text due outside those hours waits for the morning.
• Links. Carriers filter public link shorteners, so Rasket refuses them. Use your own short-link domain.

A message is up to 160 characters (70 if it has an emoji or another special character). A longer text is sent and billed as several messages. That is the unit every SMS price is in, so the question to ask is what one message costs and how the API tells you the count. On Rasket's Pro plans a message past the ones included costs $0.015, falling to $0.0125 on the largest Scale plans; Pro 50k includes 200 texts a month, and a picture message is billed as 3 messages ($0.045 on Pro). Free has 50 test texts a month to your own phones. Every text the API returns says how many messages it was and what it cost, a failed text is never charged, and POST /sms/estimate counts one before you send it. The plans themselves are on the pricing page, and SMS pricing answers the questions about texts.

Every API key starts with no SMS access, so an admin gives one access under API keys in the dashboard. Sending needs Send, on a sending_access or full_access key. Adding a test phone, the next step, needs a full_access key with Send and manage. A key limited to one sending domain cannot send texts.

Rasket texts the phone a 6-digit code from the shared test number. Confirm it with the id the first call returned.

curl -X POST "https://api.rasket.com/sms/verified-phones" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+14155550123"
}'

curl -X POST "https://api.rasket.com/sms/verified-phones/{verified_phone_id}/verify" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "481922"
}'

The only required field is to, in E.164 form, plus text for anything that is not a picture message. category is transactional unless you say marketing; a marketing text needs the contact's SMS consent and keeps to the daytime hours above. from is optional: leave it out and the text comes from your default number for the destination's country, or from the shared test number until you have one.

curl -X POST "https://api.rasket.com/sms" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
  "to": "+14155550123",
  "text": "Your order #1042 has shipped.",
  "category": "transactional",
  "tags": {
    "order": "1042"
  }
}'

The same request from Node, with the built-in fetch:

const response = await fetch("https://api.rasket.com/sms", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1042-shipped",
  },
  body: JSON.stringify({
    to: "+14155550123",
    text: "Your order #1042 has shipped.",
    category: "transactional",
    tags: {
      order: "1042"
    }
  }),
});

const { id } = await response.json();

The answer is the text itself. text is the whole text as sent, brand prefix included; segments is how many messages it was billed as; price_each and cost are in dollars; and included is true when it came out of your plan's monthly texts.

{
  "object": "sms",
  "id": "01928c3e-5b7a-7c1e-9a2f-3d4e5f60718a",
  "status": "queued",
  "from": "+18335550199",
  "to": "+14155550123",
  "text": "Acme: Your order #1042 has shipped.",
  "category": "transactional",
  "encoding": "gsm7",
  "segments": 1,
  "price_each": "0.015",
  "cost": "0.015",
  "currency": "usd",
  "included": true,
  "scheduled_at": null,
  "created_at": "2026-10-19T20:41:00.000Z",
  "tags": {
    "order": "1042"
  }
}

status moves from queued to sent to delivered, or to failed with a reason. Poll the text while you build; in production, subscribe a webhook endpoint to the SMS events instead.

curl -X GET "https://api.rasket.com/sms/{sms_id}" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"