# Use inbound TXT/SMS ![](/assets/sms-service.svg) MailSlurp supports creation and management of real mobile phone numbers in multiple regions. Phone numbers can receive inbound SMS text messages that can be read and received in code, tests, or [online](https://app.mailslurp.com). ![sms-basic](/mermaid-gen/sms-basic.mmd.svg) Common use for SMS includes testing OTP codes. See the tutorials for examples: - [Playwright SMS testing](https://www.mailslurp.com/guides/test-sms-otp-mfa-using-playwright/) - [Cypress SMS testing](https://www.mailslurp.com/guides/test-sms-cypress-js/) ## Creating phone numbers First add a phone plan to your account [subscription](https://app.mailslurp.com/pricing/). Then provision a phone number for the plan in the MailSlurp dashboard or using the API. ### Variants Some regions support phone numbers variants such as `Mobile`, and `Toll Free`. These variants affect the type of number that is allocated on our networks. Using variants can improve receiving SMS from short-code numbers. ### Create in dashboard To assign new phone number use the dashboard [phone number page](https://app.mailslurp.com/phone-numbers/). You can select from a range of phone countries and pricing plans. ![Create phone](/examples-screenshots/ms2-app/phone/create.jpeg) ### Create phone number programmatically To enable API phone creation you must first have a paid plan and enable `API creation` on the phone number overview page in the dashboard. ![enable sms](/examples-screenshots/ms2-app/phone/enable-api-creation.jpeg) Once enabled you can call the create phone number endpoints: ```javascript const phone = await mailslurp.phoneController.createPhoneNumber({ createPhoneNumberOptions: { name: 'Sales inbound', phoneCountry: CreatePhoneNumberOptionsPhoneCountryEnum.US, } }) expect(phone.phoneNumber).toContain('+1') ``` > **Info.** > Each create phone number call bills your account for a phone number rental of one month. This is because telecom providers only rent phone numbers for a minimum of one month. The phone creation endpoint is the API surface for provisioning numbers after API creation is enabled for your account. [API endpoint: `createPhoneNumber`](/docs/api/#createPhoneNumber) ## Listing phone numbers Phone numbers have an ID and a number. When fetching the phone number use the ID. Use the [PhoneControllerApi](https://js.mailslurp.com/classes/PhoneControllerApi.html) to manage phone numbers. ```javascript const mailslurp = new MailSlurp({ apiKey }); // fetch a phone number (must create phone numbers in the dashboard first) const { content: [phoneNumber] } = await mailslurp.phoneController.getPhoneNumbers({ size: 1, phoneCountry: GetPhoneNumbersPhoneCountryEnum.US }); expect(phoneNumber.phoneNumber).toEqual('+19108074451'); ``` You can fetch numbers directly using the getBy methods: ```javascript const phoneBy = await mailslurp.phoneController.getPhoneNumberByName({ name: 'Sales inbound' }) ``` ## View SMS messages In the dashboard you can view TXT message threads in the phones section: ![View SMS](/examples-screenshots/ms2-app/phone/view-thread.jpeg) Use the [SmsControllerApi](https://js.mailslurp.com/classes/SmsControllerApi.html) to view and download SMS messages. ```javascript const result = await mailslurp.smsController.getSmsMessagesPaginated({ phoneNumber: phoneNumber.id }); expect(result.totalElements).toBeGreaterThan(0); // content contains array of sms messages expect(result.content[0].body).toContain('Your code'); ``` You can fetch individual messages using the message's ID. ```javascript // fetch a message const txtMessage = await mailslurp.smsController.getSmsMessage({ smsId: sms.id // UUID of the SMS message }); expect(txtMessage.read).toEqual(true); expect(txtMessage.fromNumber).toEqual('+13252527014'); ``` For tests that need to list, inspect, or parse SMS content after receipt, pair phone-number message listing with direct SMS reads and code extraction. [API endpoint: `getSmsByPhoneNumber`](/docs/api/#getSmsByPhoneNumber) [API endpoint: `getSmsMessage`](/docs/api/#getSmsMessage) [API endpoint: `getSmsCodes`](/docs/api/#getSmsCodes) ## Send SMS You can send SMS programmatically or using the dashboard. ```javascript await mailslurp.phoneController.sendSmsFromPhoneNumber({ phoneNumberId: sendingNumber, sendPhoneNumberOptions: { to: '+14155551212', message: 'Hello from Mailslurp' } }); ``` > **Info.** > Telecom providers impose some regulations on sending. Only send to numbers that have explicitly consented to being contacted. By default MailSlurp only permits sending to numbers that have initiated contact with you. To remove this restriction contact support. ### Send a test message Use the normal send endpoint with a controlled destination and content in test environments: ```javascript await mailslurp.phoneController.sendSmsFromPhoneNumber({ phoneNumberId: sendingNumber, sendPhoneNumberOptions: { to: '+14155551212', message: 'Hello from Mailslurp' } }); ``` Use phone-scoped sending when the sender number matters. For a received inbound message, replies can be sent from the number that received it. [API endpoint: `sendSmsFromPhoneNumber`](/docs/api/#sendSmsFromPhoneNumber) [API endpoint: `replyToSmsMessage`](/docs/api/#replyToSmsMessage) ## Wait for new SMS messages Use the [WaitForControllerApi](https://js.mailslurp.com/classes/WaitForControllerApi.html) `waitForSms` methods to hold a connection open until an expected count of SMS messages is present in a phone number ```javascript // 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'); ``` This is an important technique for SMS based testing. See the [testing guide](/docs/testing/) for more information. ### Define BLOCK and ALLOW rules You can define rules for which phone numbers can send SMS to your phone numbers. This is done using [rulesets](/docs/routing-rulesets/). You can create rulesets that block or allow SMS from specific phone numbers or patterns to prevent any unwanted spam. An example looks like this: ```javascript // block SMS spam except for known numbers const blockAll = await rulesetController.createNewRuleset({ phoneId: undefined, // account wide block createRulesetOptions: { action: 'BLOCK', scope: 'RECEIVING_SMS', target: '*' } }) const allowSpecific = await rulesetController.createNewRuleset({ phoneId: undefined, // account wide permit createRulesetOptions: { action: 'ALLOW', scope: 'RECEIVING_SMS', target: '+1234567890' // replace with a known number } }) ``` In the app dashboard the interface can be found in the automations tab on the phone number overview: ![block-spam-sms.jpeg](/examples-screenshots/ms2-app/rulesets/inbox-ruleset-phone-sms-block-all.jpeg) When a test triggers an OTP or MFA flow, wait for the expected SMS instead of sleeping for a fixed delay. [API endpoint: `waitForSms`](/docs/api/#waitForSms) [API endpoint: `waitForLatestSms`](/docs/api/#waitForLatestSms)

SMS testing examples

Use these repositories for Playwright, Cypress, and C# SMS OTP test patterns.

Playwright Sms Testingplaywright example repository: playwright-sms-testing Javascript Cypress Sms Testingjavascript example repository: javascript-cypress-sms-testing Csharp Playwright Nunit Sms Otpcsharp example repository: csharp-playwright-nunit-sms-otp
## Use SMS webhooks Have SMS messages sent via HTTP POST to your server with [TXT Webhooks](/docs/webhooks/) ```javascript // 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' } }); ```