Receive SMS API with real phone numbers and webhooks

A receive SMS API gives your application a real phone number and programmatic access to the text messages it receives. With MailSlurp, you can view messages online, fetch them by API, wait for an expected message in a test, or forward new messages to your server with a webhook.

That makes one number useful for more than a manual inbox check. You can complete an SMS OTP in Playwright, route a customer reply into an application, inspect the original message after a failed test, and keep the same workflow visible in the MailSlurp dashboard.

Quick answer

Use the receive method that matches the job:

Need	Best receive method	Why
Inspect an existing message	List or fetch SMS by API	Simple retrieval when the message may already be present
Complete an OTP or MFA test	Wait for SMS	Holds the test until the expected message arrives or the timeout expires
Route replies into an application	SMS webhook	Pushes each new inbound message to your HTTP endpoint
Investigate a failed workflow	Dashboard plus API history	Keeps the message available for human review and automated assertions

For most automated tests, use a wait call for the assertion and keep the dashboard as the debugging view. For long-running integrations, use webhooks for the primary path and API retrieval when you need to inspect message history or reconcile an event.

1. Provision a real phone number

Create a phone number from the MailSlurp dashboard, or enable API phone creation and provision it in code. Phone availability and variants depend on region. A mobile or toll-free variant can matter when the system under test sends from a short code, so choose the same kind of number your real customer journey expects.

When you retrieve a phone number, keep both values:

the displayed phone number, which you give to the application that will send the SMS,
the MailSlurp phone number ID, which you use in API calls and test helpers.

const mailslurp = new MailSlurp({ apiKey });
// fetch a phone number (must create phone numbers in the dashboard first)
const { content } = await mailslurp.phoneController.getPhoneNumbers({
  size: 1,
  phoneCountry: GetPhoneNumbersPhoneCountryEnum.US,
});
const phoneNumber = content!![0]!!;
expect(phoneNumber.phoneNumber).toEqual("+19108074451");

2. Receive and read text messages

Use the SMS API to list messages for the account or fetch an individual message by its ID. The received message is the evidence your test should inspect: sender, recipient, body, and arrival time.

// fetch a message
const txtMessage = await mailslurp.smsController.getSmsMessage({
  smsId: sms.id,
});
expect(txtMessage.read).toEqual(true);
expect(txtMessage.fromNumber).toEqual("+13252527014");
// delete all messages in phone number
await mailslurp.smsController.deleteSmsMessages({
  phoneNumberId: sms.phoneNumber,
});

For a support reply or an integration test, assert the complete expected phrase when possible. For OTPs, extract the code from the received body and then prove it works in the application. A regex match alone does not prove that the user can finish signup or login.

3. Wait for the next SMS in a test

SMS delivery is asynchronous, so fixed sleeps make tests both slow and unreliable. MailSlurp wait methods hold the request until a matching message is available or the timeout is reached.

// wait for the latest unread sms
const [sms] = await mailslurp.waitController.waitForSms({
  waitForSmsConditions: {
    count: 1,
    unreadOnly: true,
    phoneNumberId: phoneNumber.id,
    timeout: 30_000,
  },
});
// extract a code from body with regex
expect(sms.body).toContain("Your code: 123");
const [, code] = /.+:\s([0-9]{3})/.exec(sms.body)!!;
expect(code).toEqual("123");

A dependable SMS test should:

assign a controlled number to the test user,
trigger the real signup, login, recovery, or reply workflow,
wait for the inbound SMS with an explicit timeout,
inspect the sender and message body,
submit the OTP or continue the reply workflow,
assert the final user-visible outcome.

Use a dedicated number per parallel worker, or make the expected message filter specific enough that one test cannot consume another test's SMS.

4. Receive SMS with a webhook

A phone-number webhook sends new inbound SMS events to your HTTP endpoint. This is the better fit when your application must react continuously instead of waiting inside a test process.

// create a webhook for a phone number to have new SMS sent to your server
const webhook = await mailslurp.webhookController.createWebhookForPhoneNumber({
  phoneNumberId: phoneNumber.id,
  createWebhookOptions: {
    eventName: CreateWebhookOptionsEventNameEnum.NEW_SMS,
    url: "https://myserver.com",
    name: "Process SMS",
  },
});

Keep the first webhook handler small: accept the event, store the message identifier and payload, and hand work to your application queue. If processing fails after receipt, you still have the original MailSlurp message available to inspect.

For implementation details, see SMS webhooks and the webhook documentation.

Receive SMS online without a shared phone

You can open the phone number in the MailSlurp dashboard and read its message thread without passing a physical device around the team. This is useful during exploratory testing and incident diagnosis, while the same number remains accessible to automated tests through the API.

Private, account-controlled numbers are a better fit for product testing than public receive-SMS pages. Public numbers can expose verification messages to other visitors and make it difficult to know which test consumed a code.

OTP, reply, and inbound-routing examples

SMS OTP and MFA

Give the MailSlurp number to the signup or login form, wait for the verification message, extract the code, enter it in the browser, and assert that the account reaches the verified state. The Playwright SMS OTP guide shows the full browser flow.

Customer replies

Use a dedicated number for a test customer, send the original notification through your normal application, then reply to that number. A webhook can route the inbound text to support or product logic while the API gives your test a second way to verify the message.

Cross-channel recovery

Some products fall back from SMS to email when a phone is unavailable. Pair the number with a MailSlurp inbox and test both paths for the same user. Confirm that an old SMS code cannot complete the flow after the email recovery path succeeds.

Common receive-SMS failures

The number receives ordinary SMS but not short codes

Check whether the selected region and number variant support the sender used by your OTP provider. Test with the same route and message type as the real authentication flow.

The test reads an older code

Do not share one number across parallel tests without message filtering. Capture the trigger time, use a fresh or isolated number when practical, and assert that the message belongs to the current user journey.

The webhook ran but downstream work is missing

Separate receipt from processing. Store enough of the event to trace the original SMS before starting work that can fail, then use the MailSlurp message history to compare what arrived with what your application processed.

The test times out intermittently

Replace fixed sleeps with a wait method and a realistic timeout. Log the phone number ID, trigger time, and messages present at failure so the CI result explains whether the problem was delivery, filtering, or application state.

FAQ

Can I receive SMS online with MailSlurp?

Yes. Provision a phone number and view inbound messages in the MailSlurp dashboard. The same messages are available through the API for tests and integrations.

Can a test wait for an SMS OTP?

Yes. Use the MailSlurp wait methods to hold the test until the message arrives, extract the code from the body, then submit it through the real signup or login flow.

Should I use polling or a webhook?

Use a wait or retrieval call when a test needs one expected message. Use a webhook when an application must process inbound messages continuously. Many teams keep API retrieval as a debugging and reconciliation path alongside webhooks.

Can MailSlurp send SMS as well as receive it?

Yes. MailSlurp supports outbound SMS from provisioned numbers. Sending is limited to consented recipients, and by default the destination must have initiated contact with your number. See the send SMS API guide for the current workflow.

Receive SMS API for Inbound Messages, OTPs, and Webhooks