Email Verification

Confirm that users own the email address they registered with using a secure token sent by Koolbase.

How it works

User registers — account is created with verified: false

Your app calls sendVerificationEmail() — Koolbase sends a one-time token to the user's email

User clicks the link — your app receives the token from the deep link

Your app calls verifyEmail(token) — account is marked verified: true

Requiring verification

By default Koolbase sends verification emails but does not enforce them — an unverified user can still sign in. To require verification, turn on Require verified contact under Auth Settings in your project dashboard.

Sign-up returns no session. The account is created, but the user is not signed in until they verify. SignUpResult.verificationRequired is true. The verification email is still sent automatically — you don't need to trigger it.
Login is refused for accounts with no verified channel, throwing ContactNotVerifiedException after the password is checked.
Existing sessions are unaffected. Anyone already signed in stays signed in until their session ends.
Social and phone sign-in still work. A verified phone or a provider identity satisfies the requirement — this is not email-only.

Check the count before turning this on

The Auth Settings page shows how many of your users have no verified email, phone, or social sign-in. Those users will not be able to sign in until they verify. On a project that has been running without enforcement this is often most of them, so read the number before you confirm.

New projects

Projects created after this feature shipped have Require verified contact on by default. Projects that existed before it have it off, so nothing changed for their users — turn it on when you are ready.

Send verification email

The verification email is sent automatically at sign-up — you don't trigger the first send yourself. To re-send it (the user missed it, the link expired, or they need a fresh one), use resendVerificationEmail() — see the next section.

Email provider

Verification emails are sent via the email provider configured in your Koolbase project settings. Make sure you have configured your EMAIL_FROM address in the dashboard before going to production.

Resend verification email

Call resendVerificationEmail() on an authenticated (but unverified) user to re-send the link. No email argument — the current session identifies the user, so a client can't request a resend for anyone else.

lib/auth.dart

Dart

final result = await Koolbase.auth.resendVerificationEmail();

if (result.alreadyVerified) {
  // Nothing was sent — the account is already verified.
} else {
  // Email re-sent. result.expiresAt is the new link's expiry;
  // result.cooldownUntil powers a "resend in N seconds" countdown.
}

It's throttled server-side to prevent abuse: a 60-second cooldown between resends and a daily cap. The automatic sign-up email doesn't count against the cooldown, so a user's first manual resend is always allowed.

lib/auth.dart

Dart

try {
  await Koolbase.auth.resendVerificationEmail();
} on ResendCooldownException {
  // Too soon — wait for the cooldown, then retry.
} on ResendDailyCapException {
  // Daily limit reached — try again tomorrow.
}

Already-verified is a no-op, not an error

If the account is already verified, the call succeeds with alreadyVerified: trueand sends nothing — no exception. Safe to call without checking status first.

Deep linking the verification email

The link in the verification email points wherever you configure your project's Verification URL under Email Branding in the dashboard. Koolbase substitutes {token} with the actual token at send time.

Common URL patterns

Universal Link (recommended for production)
  https://yourdomain.com/verify?token={token}

Custom scheme (simpler, dev-friendly)
  myapp://verify?token={token}

Universal Links vs custom schemes

Universal Links (iOS) and App Links (Android) are https URLs your app claims via apple-app-site-association and assetlinks.json hosted on your domain. They open your app when installed and fall back to a web page when it isn't — the right choice for production.

Custom schemes like myapp:// need no domain setup but have no web fallback, and some mail clients strip them. Fine for development or internal builds.

Without a configured URL

If you don't set a Verification URL in the dashboard, the link in the email falls back to a Koolbase dashboard URL that won't reach your app. Configure this before going to production.

When the user taps the link, your deep link handler extracts the token query parameter and passes it to verifyEmail() — same code path regardless of which link mechanism you chose. See the next section.

Verify the token

When the user clicks the verification link in their email, your app receives the token via deep link. Pass it to verifyEmail():

lib/auth.dart

Dart

// token comes from your deep link handler
final token = Uri.parse(incomingLink).queryParameters['token'];

await Koolbase.auth.verifyEmail(token: token!);

// User is now verified
final user = await Koolbase.auth.currentUser();
print(user?.verified); // true

Check verification status

lib/auth.dart

Dart

final user = await Koolbase.auth.currentUser();

if (user != null && !user.verified) {
  // Show verification reminder banner
  showBanner('Please verify your email to continue.');
}