RFC: Resend email verification (Auth)

[GermanJablo]

Problem:

If a user is created but does not verify their email, and later attempts to sign up again, there's currently no built-in way to handle this flow. Developers need to manually check if the user exists, regenerate the token, and resend the email, all of which is verbose, error-prone, and easy to forget entirely.

Possible Solutions

1. payload.sendVerificationEmail

This method would allow you to manually resend the email by reusing generateEmailHTML and generateEmailSubject, avoiding the complex logic surrounding tokens. However, users still have to remember to handle the case where the user was registered but not validated before calling this method. As I mentioned, it's easy to forget to do this, and there's no dedicated error status code to easily identify it.

2. New property in auth.verify

A tentative example:

const Customers: CollectionConfig = {
  // ...
  auth: {
    verify: {
      generateEmailHTML: () => void {}
      /**
       * Defines what happens if you try to create a user that already exists but hasn't been validated yet:
       * - If it's non-zero and and the previous verification email was sent more than that many milliseconds
       * ago the debounce has passed, the email will be resent.
       * - If it's non-zero but was sent more recently than the configured debounce window, the request will 
       * fail with a `429 Too Many Requests` error, including a `retryAfter` field.
       * - If the value is 0, no automatic resend will occur. The request will fail with an error indicating 
       * that the email is already registered but unverified..
       */
      emailDebounce: 5000,
    },
  },
}

3. New payload.signup method

It would be analogous to the payload.login method we already have, and could lay the groundwork for other, more advanced auth flows.

await payload.signup({
  collection: 'customers',
  data: { email, password, ... },
  /* same as explained above */
  emailDebounce: 5000, 
});

In either case, we'll likely need to revise the returned statuses to reflect the different scenarios. A suggestion:

Status	Condition	Body Shape
201 Created	New user created, verification email sent.	{ user, message: "verification-email-sent" }
202 Accepted	Existing unverified user; debounce window expired; email resent.	{ user, message: "verification-email-resent" }
409 Conflict	Existing unverified user; emailDebounce === 0.	{ error: "email-not-verified", instructions: "call /sign-up with resendIfUnverified or wait" }
429 Too Many Requests	Attempt inside active debounce window.	{ retryAfter: msRemaining }
400 Bad Request	Validation errors.	As today