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

Monthly limit

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.

Daily email recipient limit

If Clerk delivers emails for your development instances, each workspace can email a limited number of recipients per day across all of its development instances:

• 50 recipients per day for a workspace created in the last 7 days
• 100 recipients per day after that

The limit resets at midnight UTC. Each address counts once per day. Subaddresses of the same inbox, such as jane+1 and jane+2, count as separate recipients.

The following cases do not count toward the limit:

• Emails to test email addresses while test mode is enabled, because Clerk doesn't send them
• Emails to reserved domains that can't receive email, such as example.com
• Self-delivered emails (i.e., not delivered by Clerk)
• Emails for apps with a paid subscription

The limit doesn't apply to a workspace on a paid plan, or to a workspace with a production instance that has been live for at least 7 days.

Once a workspace reaches its limit, requests that email a new recipient, such as a verification code or an invitation, fail with a dev_daily_email_recipient_limit_exceeded error. Clerk drops notifications it sends on its own, such as new device sign-in alerts, without returning an error. Until the limit resets, you can still email members of your workspace and anyone you've already emailed that day.

For flows that verify with a code, use test email addresses. If your tests need to read more delivered emails, such as verification links or invitations, contact support.

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 run end-to-end tests against a production instance without Test mode, see Test against a production instance.

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