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's 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

Clerk never sends email to a test email address while Test mode is enabled. This applies to every email Clerk sends, including verification codes, verification links, invitations, and security notifications.

Testing email verification codes

When testing email verification codes, use the code 424242 to complete verification.

Testing email verification links

Clerk doesn't send verification links to test email addresses, so a test can't follow one from an inbox. Turn on the Email verification code setting and use that flow to authenticate your tests.

To test a flow that requires reading an email, such as a verification link or invitation, use an inbox you control and an address without +clerk_test. Those emails are delivered normally and count toward the development instance limits.

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')
  }
}