Email Verification — Verify and Resend Email Tokens

After registering, the API queues a verification email containing a single-use token link. You must verify your email address to unlock features that require a confirmed identity. If the original email expires or never arrives, you can request a new one while authenticated.

Verify Your Email

Submit the token from the verification email to confirm your address. The token is opaque, single-use, and valid for 24 hours.

Endpoint

POST https://api.example.com/api/v1/auth/email-verification/verify

This endpoint is public — no session cookie is required, so users can click the link from any browser.

Request Body

string

required

The verification token from your email, e.g. vrf_abc123. Tokens are single-use and expire after 24 hours.

Example Request

curl -i -X POST https://api.example.com/api/v1/auth/email-verification/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "vrf_abc123"}'

const response = await fetch(
  "https://api.example.com/api/v1/auth/email-verification/verify",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token: "vrf_abc123" }),
  }
);
const data = await response.json();

import requests

resp = requests.post(
    "https://api.example.com/api/v1/auth/email-verification/verify",
    json={"token": "vrf_abc123"},
)
print(resp.json())

Success Response — `200 OK`

{
  "success": true
}

Your email address is now verified. Subsequent calls to GET /auth/session or GET /users/me will return email_verified: true.

Error Responses

Status	Meaning	When it occurs
`400 Bad Request`	Validation error	The `token` field is missing or empty.
`404 Not Found`	Token unknown	No verification record matches the supplied token. Check that you copied the full token from the email.
`410 Gone`	Token expired or already used	The token has already been consumed or its 24-hour window has elapsed. Request a new verification email.

410 Gone means the token is no longer valid — either you already clicked the link, or the 24-hour expiry has passed. Use the Resend Verification Email endpoint below to get a fresh token.

Resend Verification Email

Request a new verification email if you did not receive the original or if your token expired. This endpoint requires you to be authenticated.

Endpoint

POST https://api.example.com/api/v1/auth/email-verification/resend

Requires an active session cookie. Because this is a state-changing POST request, you must also pass an x-csrf-token header obtained from GET /auth/csrf-token. This endpoint is rate-limited to 5 requests per 15-minute window per account.

Example Request

# Step 1 — get CSRF token
CSRF=$(curl -s -b cookies.txt \
  https://api.example.com/api/v1/auth/csrf-token \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['csrf_token'])")

# Step 2 — resend
curl -i -X POST https://api.example.com/api/v1/auth/email-verification/resend \
  -b cookies.txt \
  -H "x-csrf-token: $CSRF"

const csrfRes = await fetch(
  "https://api.example.com/api/v1/auth/csrf-token",
  { credentials: "include" }
);
const { data: { csrf_token } } = await csrfRes.json();

await fetch(
  "https://api.example.com/api/v1/auth/email-verification/resend",
  {
    method: "POST",
    credentials: "include",
    headers: { "x-csrf-token": csrf_token },
  }
);
// 202 Accepted — no response body

csrf_token = session.get(
    "https://api.example.com/api/v1/auth/csrf-token"
).json()["data"]["csrf_token"]

resp = session.post(
    "https://api.example.com/api/v1/auth/email-verification/resend",
    headers={"x-csrf-token": csrf_token},
)
# 202 Accepted

Success Response — `202 Accepted`

The response body is empty. A new verification email has been queued for delivery. Check your inbox (and spam folder) within a few minutes.

Error Responses

Status	Meaning	When it occurs
`401 Unauthorized`	Not authenticated	No valid session cookie was sent. Log in first.
`409 Conflict`	Already verified	Your email is already verified — there is nothing to resend.
`429 Too Many Requests`	Rate limited	You have requested more than 5 resends in a 15-minute window. Wait before trying again.

Verification tokens expire after 24 hours. If you request a new token, any previously issued token for the same account is invalidated immediately. Always use the link from the most recent email.

Verification Flow Summary

Create an account via POST /auth/register. The API immediately queues a verification email.

Check your inbox

Open the email and copy the token from the verification link. It looks like vrf_abc123.

Submit the token

Call POST /auth/email-verification/verify with { "token": "vrf_abc123" }. On success your email_verified flag becomes true.

Resend if needed

If the email never arrived or the token expired, call POST /auth/email-verification/resend (requires a valid session) to queue a fresh token.

Register

Create a new account — triggers the initial verification email.

Auth & Sessions

Account

Catalog

Cart & Checkout

Reviews

Email Verification — Verify and Resend Email Tokens

Verify Your Email

Endpoint

Request Body

Example Request

Success Response — `200 OK`

Error Responses

Resend Verification Email

Endpoint

Example Request

Success Response — `202 Accepted`

Error Responses

Verification Flow Summary

Register

Login

​Verify Your Email

​Endpoint

​Request Body

​Example Request

​Success Response — 200 OK

​Error Responses

​Resend Verification Email

​Endpoint

​Example Request

​Success Response — 202 Accepted

​Error Responses

​Verification Flow Summary

​Related Endpoints

Register

Login

Verify Your Email

Endpoint

Request Body

Example Request

Success Response — `200 OK`

Error Responses

Resend Verification Email

Endpoint

Example Request

Success Response — `202 Accepted`

Error Responses

Verification Flow Summary

Related Endpoints