• 228 destinations
  • No KYC, ever
  • Bitcoin, Monero, USDT and 4 more

DevelopersAdvanced8 min readUpdated 18 October 2026

Sending OTP and verification codes that arrive

Code length, validity, resend timing, fallbacks and SMS pumping defences: how to send one-time codes that arrive, convert and do not drain your balance.

Part 2 of 4 in the path Building on the API

The message

Brand first, code second, nothing else that matters: ACME: your code is 493 201. It expires in 10 minutes. Put the code early so it shows in the notification preview, and keep the text within one GSM-7 segment of 160 characters. A single curly apostrophe pasted from a design document switches the whole message to Unicode, where one segment holds 70 characters. The API never rewrites text, so the template must be clean before it ships; the encoding guide lists the usual culprits. Do not include links: operators filter codes with links more than any other pattern.

The brand belongs in the text because the sender field cannot be relied on to show it. In the Americas and China a local number replaces any name; where registration is required, a shared numeric sender is used until it is approved; and if a carrier refuses a name, that message falls back to a numeric sender. The sender ID rules explain the three cases. An alphanumeric sender is one-way, so never ask people to reply to a code.

Two additions earn their characters. Say what the code is for, to sign in or to confirm a new device, and add Never share this code: both help someone notice when a caller is trying to talk the code out of them. If your web sign-in uses autofill, end the message with a line such as @example.com #493201; Safari and Chrome on Android recognise this domain-bound format and offer the code only on that domain. Android apps that read codes with the SMS Retriever API need an 11-character app hash in the message instead.

Code length and format

Six digits is the usual choice, and the arithmetic explains why. Six digits give 1,000,000 combinations; if a code is cancelled after five wrong guesses, an attacker's chance per code is 5 in 1,000,000, or 1 in 200,000. Four digits give 10,000 combinations, and the same five guesses a 1 in 2,000 chance. Eight digits add typing for little gain.

  • Digits only. They open the numeric keypad and rule out confusing O with 0.
  • A secure random source, never a general-purpose one.
  • Text, not a number. Stored as an integer, 042817 becomes 42817 and a correct entry fails.
  • A keyed hash in storage rather than the code itself, compared in constant time and bound to one number and one purpose.
  • A space for readability, as in 493 201, helps people who type the code; if you rely on autofill, test the exact format on real devices.
Python
# Python. In Node: crypto.randomInt(0, 1000000).toString().padStart(6, "0")
import secrets
code = f"{secrets.randbelow(1_000_000):06d}"   # "042817" keeps its leading zero

Validity window

A code lives for minutes, typically five to ten. Set the message's validity, in minutes, to the same lifetime instead of leaving the default of 2,880 (48 hours). When a phone is off or out of coverage, the network keeps retrying until validity runs out: with 10 minutes the message ends as expired; with 48 hours it may arrive the next morning carrying a dead code. A code delivered after it expired is a support ticket.

Use one number everywhere: the server-side expiry, the validity field and the words in the text. If the text says ten minutes and the server accepts the code for five, a user who takes seven fails through no fault of their own.

API settings

A code request to POST /v1/messages needs a handful of settings beyond the number and the text:

HTTP
POST /v1/messages
Authorization: Bearer sk_live_...
Idempotency-Key: verify-8812-attempt-2
Content-Type: application/json

{
  "to": "+447700900123",
  "from": "ACME",
  "text": "ACME: your code is 493201. It expires in 10 minutes. Never share this code.",
  "validity": 10,
  "window": { "quiet_hours": "bypass" },
  "campaign": "otp-login",
  "reference": "verify-8812"
}
  • quiet_hours: bypass flags the traffic transactional so it leaves at any hour. Use it for codes only: promotional content flagged as transactional is treated as abuse. More on bypassing quiet hours.
  • Idempotency-Key, built from the verification and the attempt number, means a network retry on your side returns the original result instead of sending a second code. A deliberate resend is a new attempt with a new key.
  • campaign groups code traffic in reports, and reference is echoed in responses and webhooks, which is how a delivery event finds its verification.

Check encoding and segments in the response: a code template that comes back as ucs2 or two segments has a stray character in it. Give the code service its own key with the send scope only; the limit of 50 requests per second applies per key, so a bulk job on another key cannot use up the budget your codes need. Integration tests belong on a test key, which validates, prices and answers like live and fires signed webhooks without sending or billing anything.

Resend timing

Let the user ask for a new code after 30 seconds, then 60, then 120, with a visible countdown. Invalidate the previous code when you issue a new one, so only the latest is accepted, and cap the total: three or four codes per number per hour is plenty for a real person. Show the number the code went to, partly masked, with a way to edit it next to the resend button. A mistyped number is a missing code that no resend will fix.

Read the status before offering another attempt. A rejected message was refused before sending and never billed; if the error concerns the number, ask for it again. A message.failed event with an unknown-number reason means the same: tell the user to check the number instead of offering another resend. Sent without delivered is not a failure on destinations that return carrier acknowledgement only; the country page says which those are. The handler that receives these events is covered in webhooks in production.

When SMS does not arrive

There is one route per destination, chosen for measured delivery, so a second SMS takes the same path as the first. That helps when the first was lost to a passing problem. It does not help when the phone is off, roaming on a network that refuses the message, or the number is wrong. From the second code on, offer another channel next to the resend button, and switch to it outright after a failure that a resend cannot fix:

  • Email to an address already verified on the account.
  • An authenticator app or a passkey, offered at enrolment so it exists before SMS fails.
  • A voice call reading the code, through whichever provider you use for voice.
  • Backup codes issued at sign-up, for account recovery.

Apply the same limits to the fallback as to SMS: an unprotected voice fallback can be abused in exactly the same way.

Rate limits and SMS pumping

A code endpoint without limits is a way to spend your balance. The attack has several names (SMS pumping, toll fraud, artificially inflated traffic): a script requests codes for thousands of numbers in ranges where someone along the chain earns a share of the termination fee. Every number is valid, so every message is sent and billed; only messages refused before sending, the rejected ones, cost nothing. Limits per phone number do not stop it, because each request uses a different number. A prepaid balance caps the damage, but the cap is the whole balance, including what tomorrow's campaign needed.

LimitExample starting pointWhat it stops
Per phone number4 codes per hour, 10 per dayLoops, and harassment of one person
Per IP address10 codes per hour, as mobile networks share addressesSimple scripts
Per account or session5 codes per hourAbuse from signed-in sessions
Per country and prefix rangeAn hourly ceiling just above your normal peakPumping spread across many numbers
GlobalAn hourly spend ceiling that pages someoneWhatever the other limits miss

Tune the values to your own traffic; the structure matters more than the numbers. Then add the cheap defences: refuse destinations you do not serve before calling the API, require a solved challenge after the second request, validate the number format on your side, and answer the same way whether or not a number has an account, so the endpoint cannot be used to test which numbers are registered. The warning signs are a burst to a country you rarely serve, numbers that run in sequence or share a long prefix, and codes that are sent but almost never entered.

What to measure

Conversion from code sent to code entered, per destination. It is a better delivery metric than any receipt, because it includes the handset, the notification and the user, and on destinations that return carrier acknowledgement only it is the one end-to-end signal you have. Join your verification records to message events through reference, then track:

  • Conversion per destination and per attempt: entered after the first code, after the second, never.
  • Time to verify, from request to correct entry: watch the slowest tenth, not only the median.
  • Resend rate: a rise on one destination is worth an alert of its own.
  • Cost per verified user: spend divided by verifications completed.

Say a destination sends 2,000 codes in a week for a spend of 60, and 1,500 people complete verification: conversion is 75 per cent and each verified user costs 0.04. A destination that converts ten points below the others deserves a look at its sender rule and its failure reasons; a sharp fall in conversion while volume climbs is pumping until proven otherwise. Exports in CSV or JSON carry the message id, status, carrier code, timestamps and price of every message, kept for 90 days. See also the OTP verification use case.

Put it into practice.An email address opens the account. Rates are public, payment is crypto, and the test key is free.
Start sending

Something unclear or out of date? Tell us on the support page; corrections are folded back into the guide and the update date changes.