MailSlurp logo

mobile

SMS API for Real Phone Numbers, OTP Tests, and Inbound Messages

Use MailSlurp SMS APIs to provision phone numbers, receive and send texts, wait for OTP codes, and route inbound messages with webhooks.

MailSlurp's SMS API gives developers and QA teams real phone numbers that can receive text messages in code, tests, webhooks, and the dashboard. You can also send SMS from a provisioned number for approved, consent-based workflows.

The same API model works for an OTP test, a two-way support prototype, or an inbound automation: provision a number, trigger the real message path, inspect what arrived, and continue the user journey.

What you can do with the MailSlurp SMS API

Capability Use it for
Provision phone numbers Give a test user or application a real number in a supported region
List and read SMS Inspect message content, sender, recipient, and arrival evidence
Wait for SMS Complete asynchronous OTP, MFA, signup, and recovery tests
SMS webhooks Push new inbound messages to your HTTP endpoint
Send SMS Reply or send approved transactional messages to consented recipients
Rulesets Allow or block messages from selected numbers or patterns

Choose the right SMS workflow

Test an OTP or verification journey

Use a controlled phone number and a wait call. Trigger the product's real signup or login action, wait for the code, submit it, and assert the verified state. See SMS and OTP verification API for the full failure checklist.

Process inbound messages in an application

Use a webhook for the primary event path and retain API access for inspection and reconciliation. See receive SMS API for polling, wait, and webhook tradeoffs.

Send a reply or transactional message

Use a provisioned MailSlurp number and follow consent rules. By default, outbound SMS is restricted to numbers that have initiated contact. See send SMS API for the exact setup.

Provision and identify phone numbers

Create a number in the dashboard or enable API creation for your account. Phone numbers have a displayed number and a MailSlurp ID. Give the displayed value to your system under test and use the ID for API operations.

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");

If you test short-code OTP senders, check the available region and number variants before building the test around a number. Carrier behavior is part of the journey you are validating.

Read an inbound SMS

Use the SMS controller to list messages or retrieve one by its message ID.

// 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 useful assertion, verify more than the presence of digits. Check that the message belongs to the expected workflow, the sender is plausible for the environment, and the extracted code completes the intended action.

Wait for the expected message

MailSlurp wait methods remove the need for fixed sleeps in asynchronous tests.

// 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");

Set a timeout that distinguishes a genuine delivery problem from a slow environment, and include the phone number ID and trigger time in the test failure output. This makes intermittent OTP failures diagnosable in CI.

Route inbound SMS with webhooks

Create a webhook for the phone number when each new message should be sent to your server.

// 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 webhook receipt and downstream processing separate. Persist enough information to trace the original message before calling services that can fail.

Send an SMS

MailSlurp can send an SMS from a provisioned phone number. Only message recipients who have consented to be contacted. The default account policy permits sending to numbers that initiated contact with your number; contact MailSlurp support if an approved use case needs a different policy.

await mailslurp.phoneController.sendSmsFromPhoneNumber({
  phoneNumberId: sendingNumber,
  sendPhoneNumberOptions: {
    to: '+14155551212',
    message: 'Hello from Mailslurp'
  }
});

For OTP and notification products, test outbound behavior against controlled destinations before using it in a customer workflow. A successful API response is only the start: the received message and completed user action are the result that matters.

A reliable end-to-end SMS test

  1. Assign a dedicated MailSlurp number to the test user or worker.
  2. Trigger the same action a customer takes.
  3. Wait for the inbound SMS rather than sleeping for a fixed interval.
  4. Inspect the received sender and body.
  5. Extract and submit the OTP, or route the reply into the application.
  6. Assert the final verified, signed-in, recovered, or replied state.
  7. Keep the message ID and timing evidence with the failed test output.

The Playwright SMS OTP guide shows this flow in a browser test. Use programmable email and SMS APIs when the same journey includes an email code, link, or fallback.

FAQ

Does MailSlurp provide real phone numbers?

Yes. You can provision phone numbers in supported regions and control them from the dashboard or API.

Can MailSlurp receive SMS in automated tests?

Yes. Fetch an existing message or use a wait method to pause the test until the expected SMS arrives.

Can MailSlurp send SMS?

Yes, for consent-based workflows. Outbound access is restricted by default to destinations that initiated contact; contact support for other approved requirements.

Can I test email and SMS in one user journey?

Yes. MailSlurp provides programmable inboxes and phone numbers, so one test suite can cover SMS OTP, email OTP, magic links, password resets, and cross-channel recovery.