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:

Inspect an existing message: list or fetch SMS by API when the message may already be present.
Complete an OTP or MFA test: wait for SMS until the expected message arrives or the timeout expires.
Route replies into an application: use an SMS webhook to push new inbound messages to your HTTP endpoint.
Investigate a failed workflow: use the dashboard and API history to inspect the message alongside 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.

Select the number assigned to this test by ID or name. Avoid taking the first result from the account's phone list: another test or team may be using it. For concurrent suites, phone pools and leases can reserve a number for the whole application flow.

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 an individual message with mailslurp.smsController.getSmsMessage({ smsId }), using the ID of the SMS you intend to inspect. Reading a message and deleting message history are separate actions; keep debugging evidence until the test has finished.

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.

This receive-only example selects an already provisioned number explicitly. Install mailslurp-client, save the code as receive-sms.mjs, and set MAILSLURP_API_KEY and MAILSLURP_PHONE_NUMBER_ID in your environment. Run it before triggering the application's send to that number. It waits up to 60 seconds and prints message metadata rather than the OTP body.

import { MailSlurp } from 'mailslurp-client';

const apiKey = process.env.MAILSLURP_API_KEY;
const phoneNumberId = process.env.MAILSLURP_PHONE_NUMBER_ID;
if (!apiKey || !phoneNumberId) {
  throw new Error('Set MAILSLURP_API_KEY and MAILSLURP_PHONE_NUMBER_ID');
}
const mailslurp = new MailSlurp({ apiKey });
const phone = await mailslurp.phoneController.getPhoneNumber({ phoneNumberId });
const since = new Date();
console.log(`Trigger your test application's SMS to ${phone.phoneNumber}`);

const sms = await mailslurp.waitController.waitForLatestSms({
  waitForSingleSmsOptions: {
    phoneNumberId: phone.id,
    since,
    timeout: 60_000,
    unreadOnly: false,
  },
});
console.log({ smsId: sms.id, receivedAt: sms.createdAt, from: sms.fromNumber });

This script proves receipt for the selected number and time window. It does not submit the code to your application. In the automated test, also match the sender and expected content, then follow the SMS testing tutorial to verify the authenticated account. unreadOnly: false prevents a dashboard read from hiding an otherwise matching fresh message.

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.

Using the client and selected phone from the example above, register a webhook with the following call. Replace the example URL with your own HTTPS receiver before running it.

import { CreateWebhookOptionsEventNameEnum } from 'mailslurp-client';

const webhook = await mailslurp.webhookController.createWebhookForPhoneNumber({
  phoneNumberId: phone.id,
  createWebhookOptions: {
    eventName: CreateWebhookOptionsEventNameEnum.NEW_SMS,
    url: 'https://your-app.example/sms',
    name: 'Inbound 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

Check the application's send result first, then confirm the assigned number, country format and recipient. Compare messages present in MailSlurp with the wait's phone ID, time boundary and matching rule. A message can arrive but fail the test's filter. Preserve the provider message identifier and error when a send was rejected; a longer receive timeout won't correct that rejection.

Keep the phone ID, trigger time and failure status for diagnosis, without publishing OTPs or full message bodies. The missing-code checklist follows the separate application, provider, receipt and verification checks.

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.

Build with MailSlurp

Connect & learn

Receive SMS API for Inbound Messages, OTPs, and Webhooks