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);- 0.0ssign-up › receives an SMS code
- 0.3sleased +44 7700 900412 (GB, my-app) lease_8f2c41d0
- 0.9sfilled #phone, clicked “Send code”
- 3.9spoll 1: no code yet
- 6.9spoll 2: no code yet
- 7.4scode 731904 arrived from MyApp
- 8.1sfilled #code, submitted
- 9.6ssigned in as qa+checkout@myapp.test
- 9.7sreleased lease_8f2c41d0
- 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.

- 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.

Every lease on one board
- +1 202 555 0114USSign-up115482Released“Your verification code is 115482.” Released by the CI pipeline key after 41 seconds.
- +61 491 570 113AUSign-up—RestingReleased 2 minutes ago. Resting for 3 more minutes so a late text can’t reach the next test.
- +44 7700 900431GB2FA602318Released“G-602318 is your verification code.” Read on the second poll, 6 seconds after it arrived.
- +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.
- +61 491 570 156AUSign-up—WaitingLeased 9 seconds ago by Nightly regression. Polling every 3 seconds; nothing has arrived yet.
- +44 7700 900412GBReset731904Code in“Your password reset code: 731904.” From MyApp at 14:01:47. Lease ends 14:20:59.
- +1 613 555 0141CA2FA774019Released“2FA: your one-time passcode is 774019.” Arrived through the SMS gateway webhook.
- +1 202 555 0127USSign-up—ExpiredNo text in 20 minutes, so the lease expired on its own. Worth checking the app’s SMS sender.
- +44 7700 900447GBSign-up309447Released“Your sign-in code: 309-447.” Split code, joined to 309447.
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.


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
Two-letter code such as GB or US. Leave it empty for any country.