Email Verification & Resending
Verify an email address using a matching one-use token and handle invalid links.
Email verification
Email verification asks the account owner to follow a link sent to their inbox. Enable it through auth.features.emailVerification or the installed Auth settings. Set blockLoginUntilVerified when password login should wait for verification.
Follow the link
The generated email links to /verify-email?userId=...&token=... on the configured frontend. Provide that route in your theme; the sender does not create the page for you. The Auth scaffold includes a verification-page pattern.
The destination reads userId and token, then calls useWpAuth().verifyEmail(userId, token). Use the real query values, check the boolean result, and display the hook's error on failure. Treat the token as a temporary credential: do not publish it in examples, analytics events, or shared logs.
The destination needs a page
Provide the verify-email route before testing delivery. A valid email link still needs a page that reads its parameters and calls verifyEmail().
Server behavior
WordPress creates a random verification token and stores its account association in a transient for one day. Verification requires a matching token and an existing account. It consumes that token, marks the email verified, and establishes a WordPress login session.
An expired, unknown, mismatched, or already-consumed token is rejected. An account already marked verified still needs a valid token to use this endpoint; the verified flag alone never authorizes sign-in. For an old or reused link, offer normal login or a resend action when the account still needs verification.
Successful verification returns a user payload. Session restoration and navigation depend on the UI calling it; test a subsequent page request in WordPress as well as the immediate success message.
Verification outcomes
Link state Expected result Helpful next action Valid unused token for this account Verification succeeds and a session is established Continue into the account interface Expired or unknown token Verification fails Offer resend if verification is still needed Token belongs to another account ID Verification fails Use the original unmodified email link Token has already been used Verification fails Offer normal login for an already-verified account |
|---|
Give the visitor a recovery path
An invalid link should lead to a useful choice: normal login for a verified account or a resend option when verification is still pending.
Resend an email
Call resendVerificationEmail(emailOrUsername) from useWpAuth(). Although the parameter is named email in its type signature, the generated WordPress endpoint also accepts a username. The hook returns a boolean promise and exposes operation state through loading and error.
The server rejects unknown accounts and accounts already verified. Resending issues another token; it does not currently revoke every older unused token. Each token retains its own expiry and can be consumed once.
When wp_mail reports a transport failure, the resend endpoint returns an error; resendVerificationEmail() returns false and exposes the message through error. The account remains available for another resend attempt. A successful response means the transport accepted the send, not that the message reached the inbox. Verify delivery on the installed site.
Request completion and inbox delivery differ
A successful resend means WordPress mail transport accepted the message. Check inbox delivery separately. If transport fails, show the hook error and let the visitor retry.
Edit verification email text
Administrators can edit the subject and body at Settings → ForgeWP Auth. Developer defaults live under auth.emails.verification.subject and .body. The body supports {username}, {email}, and {verification_url}. These Auth email settings are separate from native-form JSON mail templates and their placeholder rules.
Local preview uses simulated verification tokens and mail logs. It does not send real verification mail or prove the WordPress token expiry, cookie, or delivery workflow.