Test emails and phones

Many of Clerk's sign-up, sign-in, and account update flows require verifying ownership of an email address or phone number, typically via a one-time password (OTP)⁠ or an email verification link. To confirm that your integration works correctly without sending real emails or SMS messages, you can simulate these verifications by using reserved test values in test mode.

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 Instance Settings⁠ page.

Email addresses

Any email with the +clerk_test subaddress is a test email address.

For example:

jane+clerk_test@example.com

doe+clerk_test@example.com

Testing email verification codes

When testing email verification codes, no email with the verification code will be sent. Instead you can use the code 424242.

Testing email verification links

When testing email verification links, an email will be sent to the test email address with a link to the verification URL. The link will be valid for 10 minutes.

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.

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

Code examples

Testing sign in via email code

The following example uses an email address to sign in, with an email verification code to verify the user. To find other flow examples, see the custom flow guides. This example uses the email/phone OTP custom flow.

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

  // Use a test email address to create the sign in attempt
  await signIn.create({ identifier: 'john+clerk_test@example.com' })

  // Calling `sendCode()` is still required even though no email will be sent
  await signIn.emailCode.sendCode()

  // Use the test code to verify the email address
  await signIn.emailCode.verifyCode({ code: '424242' })

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

Testing sign up with phone number

The following example uses a phone number to sign up, with an SMS verification code to verify the user. To find other flow examples, see the custom flow guides. This example uses the email/phone OTP custom flow.

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

  // Use a test phone number to create the sign up attempt
  await signUp.create({
    phoneNumber: '+12015550100',
  })

  // Calling `sendPhoneCode()` is still required even though no SMS will be sent
  await signUp.verifications.sendPhoneCode()

  // Use the test code to verify the phone number
  await signUp.verifications.verifyPhoneCode({
    code: '424242',
  })

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