Email verification

After a user signs up (via password, OAuth with an unverified email, etc.), you usually want to confirm they own the email address. The email-verification flow uses the same primitive as magic-code sign-in, but gated on an authenticated session. It sends a code (6 digits by default) to the user’s email field and stamps emailVerified on a successful verify. The OAuth and SSO sign-in paths stamp emailVerified automatically, because the upstream IdP already verified the email. Use this flow when the IdP did not verify the email (manual signup, edit-email flow, etc.).

Endpoints

Endpoint	Method	Auth	Purpose
`/api/auth/email/send-verification`	POST	session	Email a code to the user’s current email
`/api/auth/email/verify`	POST	session	Submit the code; stamp `emailVerified`

Schema

The User entity needs an emailVerified field. Pylon writes the current ISO 8601 timestamp on success:

import { entity, field } from "@pylonsync/sdk";

export const User = entity("User", {
  email: field.string().unique(),
  emailVerified: field.string().optional(),  // ISO 8601 — null = not verified
  // ...
});

If your schema lacks this field, update rejects the unknown column and /email/verify returns 500 PERSIST_FAILED (with a hint to add an emailVerified datetime field to the User entity) instead of silently succeeding.

Sending a verification code

curl -X POST https://your-app/api/auth/email/send-verification \
  -H 'Authorization: Bearer pylon_token'

Pylon looks up the caller’s User row, reads email, creates a code, and sends an email with subject "Verify your email address" through the configured email transport. Body: "Your email verification code is: <code>\n\nThis code will expire in 10 minutes.". Override both with PYLON_EMAIL_TEMPLATE_EMAIL_VERIFY_SUBJECT and PYLON_EMAIL_TEMPLATE_EMAIL_VERIFY_BODY. The response includes codeLength. Response in production:

{ "sent": true, "email": "[email protected]" }

Response in dev (PYLON_DEV_MODE=true) to a request from the same machine:

{ "sent": true, "email": "[email protected]", "dev_code": "123456" }

Errors:

Status	Code	Reason
401	`UNAUTHORIZED`	No session
404	`USER_NOT_FOUND`	Session resolves to a user_id with no matching row
400	`MISSING_EMAIL`	User row has no `email` field
429	`RATE_LIMITED`	A code was requested within the throttle window
500	`EMAIL_SEND_FAILED`	Email transport returned an error

The throttle is shared with magic-code sends: 1 code per email per minute. The 10-minute TTL is shared too.

Verifying

curl -X POST https://your-app/api/auth/email/verify \
  -H 'Authorization: Bearer pylon_token' \
  -H 'Content-Type: application/json' \
  -d '{"code": "123456"}'

Response on success:

{ "verified": true, "emailVerified": "2026-01-15T10:30:00Z" }

Pylon stamps emailVerified to the current ISO 8601 timestamp and echoes it back in the response. Errors:

Status	Code	Reason
401	`UNAUTHORIZED`	No session
400	`MISSING_CODE`	`code` field absent
400	`INVALID_JSON`	Body wasn’t JSON
4xx	`INVALID_CODE`	Wrong code, expired, or burned

Gating handlers on `emailVerified`

In your TS code:

import { action } from "@pylonsync/functions";

export default action({
  async handler(ctx, args) {
    if (!ctx.auth.userId) throw new Error("sign in");
    const user = await ctx.db.get("User", ctx.auth.userId);
    if (!user?.emailVerified) {
      throw ctx.error("EMAIL_NOT_VERIFIED", "Verify your email before posting");
    }
    // proceed
  },
});

In policies, project emailVerified from the User entity and reference it directly:

import { policy } from "@pylonsync/sdk";

export const postsPolicy = policy({
  entity: "Post",
  // Pull the related user's emailVerified through the relation.
  allowInsert: "auth.userId == data.authorId",
  allowRead: "true",
});

Pylon does not add auth.emailVerified to the policy DSL today. The field lives on your User row. You reference it through your own handlers or queries.

Security guarantees

Code generation, comparison, throttling shared with magic-codes — numeric (6 digits by default, PYLON_AUTH_CODE_LENGTH), 10-minute TTL, burn-after-5-wrong-attempts, the same daily wrong-guess limit per email (429 CODE_LOCKED), constant-time comparison.
Session-gated — only the authenticated user can request and verify their own email. There is no admin override. To mark an email verified from another process, write the User row directly with admin auth.
ISO 8601 timestamp format — pylon_kernel::util::now_iso() produces 2026-01-15T10:30:00Z. An email is verified only when emailVerified is non-null.

Where to go next

Magic codes — the same code primitive as a primary sign-in flow
Password — the register flow that produces an unverified email

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

Email verification

Endpoints

Schema

Sending a verification code

Verifying

Gating handlers on `emailVerified`

Security guarantees

Where to go next

​Endpoints

​Schema

​Sending a verification code

​Verifying

​Gating handlers on emailVerified

​Security guarantees

​Where to go next

Endpoints

Schema

Sending a verification code

Verifying

Gating handlers on `emailVerified`

Security guarantees

Where to go next