> ## Documentation Index
> Fetch the complete documentation index at: https://codebyahmed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Email Verification — Verify and Resend Email Tokens
> Verify your registration email using the single-use token from your inbox, or request a new verification email if the original expired.
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
```http theme={null}
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
The verification token from your email, e.g. `vrf_abc123`. Tokens are single-use and expire after 24 hours.
### Example Request
```bash cURL theme={null}
curl -i -X POST https://api.example.com/api/v1/auth/email-verification/verify \
-H "Content-Type: application/json" \
-d '{"token": "vrf_abc123"}'
```
```js JavaScript (fetch) theme={null}
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();
```
```python Python (requests) theme={null}
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`
```json theme={null}
{
"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](#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
```http theme={null}
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
```bash cURL theme={null}
# 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"
```
```js JavaScript (fetch) theme={null}
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
```
```python Python (requests) theme={null}
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.
Open the email and copy the token from the verification link. It looks like `vrf_abc123`.
Call `POST /auth/email-verification/verify` with `{ "token": "vrf_abc123" }`. On success your `email_verified` flag becomes `true`.
If the email never arrived or the token expired, call `POST /auth/email-verification/resend` (requires a valid session) to queue a fresh token.
## Related Endpoints
Create a new account — triggers the initial verification email.
Log in to get a session before resending a verification email.