Test emails and phones

Most of Clerk's sign-in and sign-up flows involve verifying ownership of an email address or phone number via a one-time password (OTP)⁠. To confirm that your integration works correctly, you can simulate verification flows without sending an email or SMS, by using reserved values in test mode.

Verification messages are used during sign-up, sign-in, and when adding an email address or phone number to an existing account.

Limitations

If Clerk is used to deliver SMS messages and/or emails for your development instance, a maximum of 20 SMS messages and 100 emails can be delivered per calendar month.

After that, requests resulting in SMS and/or email OTPs⁠ will be rejected. Other SMS or email notifications will still produce a webhook but won't be sent to the target address.

The following cases do not count toward the limit:

• SMS messages sent to US numbers
• SMS messages or emails sent to test numbers/addresses
• Self-delivered SMS messages or emails (i.e. not delivered by Clerk)
• SMS messages or emails for apps with a paid subscription

If your development instance requires a higher allowance of monthly SMS messages or emails, contact support to request a limit increase.

Set up test mode

Every development instance has test mode enabled by default. If you need to use test mode on a production instance, you can enable it in the Clerk Dashboard. However, this is highly discouraged.

To enable or disable test mode, in the Clerk Dashboard, navigate to the Settings⁠ page.

Email addresses

Any email with the +clerk_test subaddress is a test email address. No emails will be sent, and they can be verified with the code 424242.

For example:

jane+clerk_test@example.com

doe+clerk_test@example.com

Phone numbers

Any fictional phone number⁠ is a test phone number. No SMS will be sent, and they can all be verified with the code 424242.

Fictional phone numbers have the following structure:

+1 (XXX) 555-0100 to +1 (XXX) 555-0199

For example:

+12015550100

+19735550133

Email links

Testing email links in E2E suites is an uphill task. We recommend turning on the Email verification code setting, and using that flow to authenticate your tests. The flows are very similar.

Code examples

Testing sign in via email code

const testSignInWithEmailCode = async () => {
  const { signIn } = useSignIn()

  const emailAddress = 'john+clerk_test@example.com'
  const signInResp = await signIn.create({ identifier: emailAddress })
  const { emailAddressId } = signInResp.supportedFirstFactors.find(
    (ff) => ff.strategy === 'email_code' && ff.safeIdentifier === emailAddress,
  )! as EmailCodeFactor

  await signIn.prepareFirstFactor({
    strategy: 'email_code',
    emailAddressId: emailAddressId,
  })

  const attemptResponse = await signIn.attemptFirstFactor({
    strategy: 'email_code',
    code: '424242',
  })

  if (attemptResponse.status == 'complete') {
    console.log('success')
  } else {
    console.log('error')
  }
}

Testing sign up with phone number

const testSignUpWithPhoneNumber = async () => {
  const { signUp } = useSignUp()

  await signUp.create({
    phoneNumber: '+12015550100',
  })
  await signUp.preparePhoneNumberVerification()

  const res = await signUp.attemptPhoneNumberVerification({
    code: '424242',
  })
  if (res.verifications.phoneNumber.status == 'verified') {
    console.log('success')
  } else {
    console.log('error')
  }
}