Quickstart: SMS

$ npm install -D mailfixture

$ pip install mailfixture

# no install — curl ships with your OS.
# you'll want jq for the examples below.

MAILFIXTURE_API_KEY=mfx_••••••••••••••••••••

import { MailFixture } from 'mailfixture';

const mail = new MailFixture(); // reads MAILFIXTURE_API_KEY

async function createActiveNumber() {
  let number = await mail.createPhoneNumber();
  const deadline = Date.now() + 90_000;
  while (number.status !== 'active' && Date.now() < deadline) {
    await new Promise((resolve) => setTimeout(resolve, 2_000));
    number = (await mail.listPhoneNumbers()).find((n) => n.id === number.id) ?? number;
  }
  if (number.status !== 'active') throw new Error('phone number did not activate');
  return number;
}

import time
from mailfixture import MailFixture

mf = MailFixture()  # reads MAILFIXTURE_API_KEY

def create_active_number():
    number = mf.create_phone_number()
    deadline = time.monotonic() + 90
    while number.status != "active" and time.monotonic() < deadline:
        time.sleep(2)
        number = next((n for n in mf.list_phone_numbers() if n.id == number.id), number)
    if number.status != "active":
        raise RuntimeError("phone number did not activate")
    return number

$ curl -X POST https://api.mailfixture.com/v1/phone-numbers \
    -H "Authorization: Bearer $MAILFIXTURE_API_KEY"
→ {"id":"7c2e41b0-…","phone_number":"+12015550137","status":"active"}
# status may briefly be "pending" — poll GET /v1/phone-numbers until active

import { test, expect } from '@playwright/test';
import { MailFixture } from 'mailfixture';

const mail = new MailFixture();

test('signup verifies a phone number', async ({ page }) => {
  const number = await createActiveNumber(); // helper from step 3

  try {
    await page.goto('/signup');
    await page.fill('#phone', number.phoneNumber);
    await page.click('text=Send code');

    const otp = await number.waitForOtp({ timeout: 30_000 });
    await page.fill('#otp', otp);

    await expect(page.locator('h1')).toHaveText('Welcome');
  } finally {
    await number.release();
  }
});

from mailfixture import MailFixture

mf = MailFixture()

def test_signup_verifies_phone(page):
    number = create_active_number()  # helper from step 3

    try:
        page.goto("/signup")
        page.fill("#phone", number.phone_number)
        page.click("text=Send code")

        otp = number.wait_for_otp(timeout=30)
        page.fill("#otp", otp)
    finally:
        number.release()

# …trigger your app's SMS verification, then long-poll for the text:
$ curl "https://api.mailfixture.com/v1/phone-numbers/7c2e41b0-…/messages?wait=45" \
    -H "Authorization: Bearer $MAILFIXTURE_API_KEY" | jq -r .messages[0].id
→ 0198a3f2-…   # summaries include the full text body

# the extracted OTP is its own endpoint, same shape as email:
$ curl "https://api.mailfixture.com/v1/sms/0198a3f2-…/otp" \
    -H "Authorization: Bearer $MAILFIXTURE_API_KEY" | jq -r .best
→ 482913

let number;

test.beforeAll(async () => {
  test.setTimeout(120_000); // the activation poll can outlive the 30s hook default
  number = await createActiveNumber();
});
test.afterAll(async () => { await number.release(); });

# conftest.py
@pytest.fixture(scope="session")
def number(mf):
    number = create_active_number()
    yield number
    number.release()

# releasing deletes the number's messages with it
$ curl -X DELETE https://api.mailfixture.com/v1/phone-numbers/7c2e41b0-… \
    -H "Authorization: Bearer $MAILFIXTURE_API_KEY"