Mailmus
Auth

Phone sign-in (SMS)

SMS one-time codes — no provider account to create, and testable on Free with your own number.

As with email, Mailmus generates and verifies the 6-digit code itself — the SMS is only transport. No SMS provider account to create or configure on your side: Mailmus hosts and pays for the sending.

Why the behaviour differs by tier

Unlike email (nearly free) and OAuth (no per-sign-in cost), SMS has a real cost per message sent.

  • Pro tier: PHONE_CODE works without restriction, to any number.
  • Free tier: PHONE_CODE can be turned on, but sends are restricted to a single test number, which you verify yourself from the dashboard — see below. It is meant for testing the flow under real conditions before going to production, not for serving real Customers.

Turn it on

Project → Authentication → Sign-in methods, turn on "SMS / phone code".

Test number (Free tier)

Once PHONE_CODE is on for a Free project, a "Test number (Free tier)" card appears in the Auth settings:

  1. Enter your own number and click "Send the code" — you receive an SMS with a 6-digit code.
  2. Enter that code to verify the number.

Once verified, requestPhoneOtp/verifyPhoneOtp (SDK or raw API) work only towards that number — any other request fails with 403 "Free tier: only the verified test number can receive a code...". That verification goes through the authenticated dashboard only, never through the public sign-up API — so an anonymous visitor to your app cannot use it to have free SMS sent.

Test-number limits:

  • Changeable up to 3 times after the initial verification (4 verifications in total), then locked until you move to the Pro tier.
  • Capped at 20 sends per month, on top of the standard throttle on public routes.

Move to the Pro tier to lift both restrictions and open PHONE_CODE to your Customers.

Browser SDK

// 1. Request a code — sent by SMS.
await auth.requestPhoneOtp({ phone: "+33612345678" }); // E.164 format required (the "+" included)

// 2. Verify the code the user entered.
const result = await auth.verifyPhoneOtp({ phone: "+33612345678", code: "123456" });

if (isMfaChallenge(result)) {
  // As with any other provider — MFA applies to phone sign-in too.
  const { customer } = await auth.mfa.verify({ challengeToken: result.challengeToken, code: "654321" });
} else {
  console.log(result.customer);
}

Same contract as requestOtp/verifyOtp (email): requestPhoneOtp returns nothing (fire-and-forget), and verifyPhoneOtp returns either a session or an MFA challenge.

With @mailmus/auth-react / @mailmus/auth-react-native

<SignIn>/<SignUp> detect PHONE_CODE in the project configuration and add the SMS method to the available options — no extra code to write, and the same MFA challenge handled internally as for the other providers.

Next

  • MFA — it applies the same way, whatever the first-sign-in provider.
  • Add authentication — an overview of the SDKs.
  • API Reference — the phone-otp and phone-otp/verify endpoints.

On this page