> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Finish a sign-up that sends a code

> Read email and SMS verification codes for your own test sign-up flow.

Use a Mobilerun mailbox and an optional phone number to test verification in your own application.

> [accordion] Setup (once)
>
> ```bash Python theme={null}
> pip install mobilerun-sdk
> export MOBILERUN_API_KEY=dr_sk_...   # API Keys page
> export DEVICE_ID=...                 # a ready device from the dashboard
> python example.py
> ```
>
> ```bash TypeScript theme={null}
> npm init -y && npm pkg set type=module
> npm install @mobilerun/sdk && npm install -D tsx
> export MOBILERUN_API_KEY=dr_sk_...   # API Keys page
> export DEVICE_ID=...                 # a ready device from the dashboard
> npx tsx example.ts
> ```

> [!NOTE]
>
> These examples require an active mailbox or number. This walkthrough was not verified end to end: the test account required payment checkout before either resource could be activated. Never log verification codes or use this flow on accounts without permission.

## Read an email code

Request a fresh code from a test app you control, then wait for it with `mailbox.waitForOtp()` (Python `wait_for_otp`). The API returns the most likely code, not proof that a sign-up succeeded.

**Needs:** A Mobilerun API key and an active mailbox; included mailbox entitlement or paid rental after checkout. Check the displayed checkout price before confirming. No device or third-party account is needed. Set `MOBILERUN_API_KEY` and `MAILBOX_ID`. This is a one-shot wait for up to two minutes; message allowance and mailbox rental may apply.

Create a mailbox with `mobilerun.mailboxes.create()` and check that `mailbox.status` is `active` (`mailbox.refresh()` updates it). If it is `awaiting_payment`, complete checkout from its `checkoutUrl` before continuing. Reuse the active mailbox ID; do not create a mailbox on every run. Configure your test app to send a code to that mailbox, and trigger it after the script starts. The test app must be able to send real email; this example does not send email itself.

> **MCP prompt:** Find my active test mailbox, wait for a new verification code from my test app, and report only whether a code arrived. Do not disclose the code.

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import os
> from datetime import datetime, timezone
> from mobilerun_sdk import MobilerunSDK
>
> mobilerun = MobilerunSDK()
> mailbox = mobilerun.mailboxes.from_id(os.environ['MAILBOX_ID'])
> after = datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', 'Z')
> print('Request a code from your test app now; waiting up to 2 minutes.')
> otp = mailbox.wait_for_otp(after=after, timeout=120)  # raises WaitTimeoutError if no code arrives
> print('Code received; message ID:', otp.message_id)
> # Use otp.code in your test; never print it in CI logs.
> ```
>
> ```typescript TypeScript theme={null}
> import { MobilerunSDK } from '@mobilerun/sdk';
>
> const mobilerun = new MobilerunSDK();
> const mailbox = mobilerun.mailboxes.fromId(process.env.MAILBOX_ID!);
> const after = new Date().toISOString();
> console.log('Request a code from your test app now; waiting up to 2 minutes.');
> const otp = await mailbox.waitForOtp({ after }, { timeoutMs: 120_000 }); // throws WaitTimeoutError if no code arrives
> console.log('Code received; message ID:', otp.messageId);
> // Use otp.code in your test; never print it in CI logs.
> ```

Result

Expected: a code is received; do not print it. This example was not verified end to end.

## Complete test sign-up verification

The first task requests a code; the script fetches it and starts a second task to enter it. Point the URL at your own test build. The second task assumes the verification form is still open on the same device.

**Needs:** the mailbox from above, plus a ready Cloud Android device with Chrome, device minutes and agent credits; set `DEVICE_ID` and `TEST_SIGNUP_URL` to an HTTPS test form reachable by the device. No consumer-service account. One-shot; each task can take up to six minutes, then up to two minutes waiting for the email. Agent task instructions contain the mailbox address and verification code: use only test data and restrict access to task history.

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import os
> from datetime import datetime, timezone
> from mobilerun_sdk import MobilerunSDK
>
> mobilerun = MobilerunSDK()
> device = mobilerun.devices.from_id(os.environ['DEVICE_ID'])
> mailbox = mobilerun.mailboxes.get(os.environ['MAILBOX_ID'])
> if mailbox.status != 'active' or not mailbox.address:
>     raise RuntimeError('Mailbox must be active')
>
> after = datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', 'Z')
> device.run(
>     task=f"Open Chrome at {os.environ['TEST_SIGNUP_URL']}. Enter {mailbox.address} "
>          'in the test sign-up form, request a verification code, and stop at the code field.',
>     max_steps=30,
> ).wait(timeout=360)
> otp = mailbox.wait_for_otp(after=after, timeout=120)
> device.run(
>     task=f'Enter the verification code {otp.code} in the current form and finish the test sign-up.',
>     max_steps=30,
> ).wait(timeout=360)
> print('Verification task completed')
> ```
>
> ```typescript TypeScript theme={null}
> import { MobilerunSDK } from '@mobilerun/sdk';
>
> const mobilerun = new MobilerunSDK();
> const device = mobilerun.devices.fromId(process.env.DEVICE_ID!);
> const mailbox = await mobilerun.mailboxes.get(process.env.MAILBOX_ID!);
> if (mailbox.status !== 'active' || !mailbox.address) throw new Error('Mailbox must be active');
>
> const after = new Date().toISOString();
> const signup = await device.run({
>   task: `Open Chrome at ${process.env.TEST_SIGNUP_URL}. Enter ${mailbox.address} in the test sign-up form, request a verification code, and stop at the code field.`,
>   maxSteps: 30,
> });
> await signup.wait({ timeoutMs: 360_000 });
> const otp = await mailbox.waitForOtp({ after }, { timeoutMs: 120_000 });
> const verify = await device.run({
>   task: `Enter the verification code ${otp.code} in the current form and finish the test sign-up.`,
>   maxSteps: 30,
> });
> await verify.wait({ timeoutMs: 360_000 });
> console.log('Verification task completed');
> ```

Result

Expected: the test verification completes. This example was not verified end to end.

## Read an SMS code

Use a number that has already been provisioned. Poll inbound messages after the script starts, looking for a six-digit code. Adapt the expression and filter sender or message content for your own app; an unrelated message may otherwise match.

**Needs:** A Mobilerun API key, an active SMS-capable number, and a test service you control that can send SMS to it. Set `MOBILERUN_API_KEY` and `NUMBER_ID`. No device is needed. Number entitlement or rental, checkout, and sender SMS charges may apply; confirm the displayed price. The script polls for up to two minutes; stop early with Ctrl+C.

Use `mobilerun.numbers.countries()` to find available countries, then `mobilerun.numbers.create(country=...)` (Python) or `mobilerun.numbers.create({ country: ... })` (TypeScript). `number.waitUntilActive()` (Python `wait_until_active`) returns once the number is `active`; a paid rental can require checkout. Reuse the number rather than purchasing one on each run. Start the script before triggering your test SMS. SMS delivery and code extraction were not live-tested here.

> [accordion] Show the code (Python and TypeScript)
>
> ```python Python theme={null}
> import os
> import re
> import time
> from datetime import datetime, timezone
> from mobilerun_sdk import MobilerunSDK
>
> mobilerun = MobilerunSDK()
> number = mobilerun.numbers.get(os.environ['NUMBER_ID'])
> if number.state != 'active':
>     raise RuntimeError('Number must be active')
> since = datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', 'Z')
> print('Request an SMS code from your test app; waiting up to 2 minutes.')
> # The SDK has no helper that waits for an incoming SMS, so poll the number.
> for _ in range(24):
>     for message in number.messages.list(direction='inbound', since=since):
>         match = re.search(r'\b\d{6}\b', getattr(message.info, 'body', None) or '')
>         if match:
>             print('SMS code received; message ID:', message.id)
>             # Use match.group(0) in your test without logging it.
>             raise SystemExit(0)
>     time.sleep(5)
> raise TimeoutError('No matching SMS arrived')
> ```
>
> ```typescript TypeScript theme={null}
> import { MobilerunSDK } from '@mobilerun/sdk';
>
> const mobilerun = new MobilerunSDK();
> const number = await mobilerun.numbers.get(process.env.NUMBER_ID!);
> if (number.state !== 'active') throw new Error('Number must be active');
> const since = new Date().toISOString();
> console.log('Request an SMS code from your test app; waiting up to 2 minutes.');
> // The SDK has no helper that waits for an incoming SMS, so poll the number.
> for (let i = 0; i < 24; i++) {
>   for await (const message of number.messages.list({ direction: 'inbound', since })) {
>     const info = message.info;
>     const match = (info && 'body' in info ? info.body : undefined)?.match(/\b\d{6}\b/);
>     if (match) {
>       console.log('SMS code received; message ID:', message.id);
>       // Use match[0] in your test without logging it.
>       process.exit(0);
>     }
>   }
>   await new Promise(resolve => setTimeout(resolve, 5000));
> }
> throw new Error('No matching SMS arrived');
> ```

Result

Expected: a code is received; do not print it. This example was not verified end to end.

## Run it on many devices

> [!TIP]
>
> Use a separate test mailbox and device for each parallel sign-up.

These examples run one verification at a time; coordinate separate runs for parallel tests.

**Needs:** A separate ready device and active test mailbox per sign-up · device minutes and task credits per run.

Result

Expected: each test sign-up is verified independently. Parallel runs were not verified here.

## Next steps

* Review the [API key guide](https://docs.mobilerun.ai/api-keys.md) for mailbox and number endpoints.
* Use a dedicated test mailbox and number. Release rentals when you no longer need them.

> [accordion] For AI agents
>
> Start with the first example on a ready device the user names. Uses `mailbox.waitForOtp`, number messages, and optionally `device.run`. Ask before creating or renting mailboxes/numbers or completing a test sign-up; never purchase resources or use real accounts. Report the result and any failed step.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.