Real numbers foryour SMS tests

Relay leases your test suite a phone number you own, catches the verification text, and hands back the code. Self-hosted, on your Twilio numbers or your own gateway.

+44 7700 900412
🇬🇧 United Kingdom · My app
20:00
482910the one 4–8 digit run that isn’t a year

How tests use it

Lease a number.

One POST picks a free number in the country you ask for and holds it for your test for 20 minutes.

Then let your app text it.

Your test types the number into your own sign-up form. Relay listens while your app sends the code.

Read the code, then release.

Poll every few seconds. When the code lands, type it in and release the number for the next run.

Drop it into any test runner

Four HTTP calls with a bearer key: lease, poll, read, release. Playwright, Cypress, pytest or a shell script all work the same way.

const H = { Authorization: `Bearer ${KEY}` };

// lease a number you own
const { number } = await post("/api/v1/numbers",
  { service: "my-app", country: "GB" }, H);

// let your app text it
await page.fill("#phone", number.number);
await page.click("text=Send code");

// read the code, then release
const code = await poll(`/api/v1/numbers/${number.id}/otp`, H);
await page.fill("#code", code);
await del(`/api/v1/numbers/${number.id}`, H);
Example run · sign-up.spec.tspassed
  1. 0.0ssign-up › receives an SMS code
  2. 0.3sleased +44 7700 900412 (GB, my-app) lease_8f2c41d0
  3. 0.9sfilled #phone, clicked “Send code”
  4. 3.9spoll 1: no code yet
  5. 6.9spoll 2: no code yet
  6. 7.4scode 731904 arrived from MyApp
  7. 8.1sfilled #code, submitted
  8. 9.6ssigned in as qa+checkout@myapp.test
  9. 9.7sreleased lease_8f2c41d0
  10. 1 passed (9.8s)

What Relay handles

  • Lease a number

    Pick a country or take any free number. It’s held for 20 minutes, up to five at once, and you can release it early.

    Relay’s active leases: one number waiting for a text, two showing codes 731904 and 482910.
  • Catch the code
  • Sort numbers by country
  • A key per pipeline
  • Rest between leases
  • Signed webhooks

Pick a country or take any free number. It’s held for 20 minutes, up to five at once, and you can release it early.

Relay’s active leases: one number waiting for a text, two showing codes 731904 and 482910.

Every lease on one board

  • +1 202 555 0158USCheckout482910Code in“MyApp: Your verification code is 482910. It expires in 10 minutes.” From MyApp at 14:02:11. Lease ends 14:21:40.

The SMS step, before and after

Without Relay

  • The code goes to someone’s own phone, and a person reads it out to the test.
  • CI mocks the SMS step, so your real sender is never tested before release.
  • Shared test numbers collect texts from every run at once, and tests read each other’s codes.

With Relay

  • Each test leases its own number and reads the code through the API.
  • Your app’s real SMS sender runs on every build, on numbers you own.
  • One lease per test and a five-minute rest before reuse, so texts never cross.

Built for the people who ship sign-up

  • QA engineers

    Run the real SMS step in every regression pass instead of skipping it or reading a code off a desk phone.

  • Backend developers

    Try a new SMS template, sender ID or provider end to end before a single user receives it.

  • Release managers

    Gate a release on sign-up actually delivering a code, with the lease history to show for it.

The limits, in plain numbers

minutes a lease lasts
20
numbers each account can hold at once
5
minutes a number rests after release
5
API keys per account
5

Named for the telegraph relay

On long telegraph lines, a relay listened for a faint signal and sent it on at full strength down the next stretch of wire. Relay does the same small job for your tests: it listens on a number and passes the code along.

A Lorenz teleprinter typing out an incoming message on its own.
A brass polarized telegraph relay with a glass top on a round mahogany base, maker's plate reading Siemens Halske & Comp, London.
Polarized relay, Siemens, Halske & Co., London, 1858–65
A telegraph relay under a glass dome on a black base: a brass column, an electromagnet coil and a contact arm, with five brass terminals.
Relay under glass, Melbourne Observatory, 1860s–90s

Questions

Which numbers does Relay use?

Only numbers you own. Turn on the Twilio sync to bring in your Twilio numbers, or add numbers from your own SMS gateway or modem in Inventory. Relay never buys or rents numbers for you.

Can I use it to sign up to other companies’ apps?

No. Relay is for testing your own product’s sign-up, login and 2FA flows. Using it to create or verify accounts on someone else’s service breaks their terms, and it isn’t what Relay is built for.

How long does a lease last?

Twenty minutes, and each account can hold five at once. Release a number as soon as your test has its code; it rests for five minutes and then goes back in the pool.

What stops a late text reaching the wrong test?

The rest period. A message is only attached to the lease that was active when it arrived, and a released number can’t be leased again for five minutes.

How does it find the code in a message?

It looks for a code next to words like “code”, “PIN” or “OTP” first, then G- prefixed codes, then 3-3 split codes, then a lone 4–8 digit run that isn’t a year. The whole message is always kept, so nothing is lost if a format is unusual.

How do texts reach Relay?

Twilio numbers post to Relay’s Twilio webhook, which checks Twilio’s signature. Anything else posts to the inbound webhook with a shared secret. Texts to numbers that aren’t in your pool are refused.

Where does the data live?

On your server. Relay is self-hosted; messages, leases and hashed API keys stay in your own store. Move it to Postgres before you run more than one instance.

What does it cost?

Relay itself is yours to run. You pay your carrier for the numbers and the texts they receive, as you do today.

Test the
SMS step

Self-hosted on your server, with numbers you already pay your carrier for. The button opens the dashboard with this lease ready; add your numbers in Inventory first if the pool is empty.

Lease a number

Who sends the text

Two-letter code such as GB or US. Leave it empty for any country.

Open the dashboard