payloadcms / payloadcms/payload

Local API verifyEmail throws an error instead of returning false

Open
#14,682 0 comments 0 reactions 1 assignee View on GitHub

@zubricks is already working on this.

Since Nov 20, 2025.

Dominant language
TypeScript
Stars
44.8k
Forks
4.2k
Avg merge
2d 21h
Merged PRs (30d)
53

Description

Documentation Issue

In the docs https://payloadcms.com/docs/local-api/overview#verify it is stated that the result of await payload.verifyEmail "will be a boolean representing success or failure".

// Returned result will be a boolean representing success or failure
const result = await payload.verifyEmail({
  collection: 'users', // required
  token: 'afh3o2jf2p3f...', // the token saved on the user as `_verificationToken`
})

But while using this method I figured it is never returning false but throwing an error instead. This can be a problem if someone (like me 😄) expects a boolean value for a graceful handling of a false case.

Additional Details

Instead of changing the documentation I would rather propose to change the method to create the behavior described in the docs.
The proposal would be to change this line when a user with the verify token wasn't found verifyEmail.ts L46

    // Before
    if (!user) {
      throw new APIError('Verification token is invalid.', httpStatus.FORBIDDEN)
    }

    // After
    if (!user) {
      return false
    }

The same problem might exist for REST and GraphQL as well.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.