> ## 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.
# Update Your Account Email Address with Verification
> Request an email change with your new address and current password. A verification link is sent to the new address; confirm it to complete the change.
Changing your email address is a two-step process that protects against unauthorized account takeovers. First, you initiate the change by providing your new address along with your current password to confirm your identity. The API then sends a verification link to the new inbox. Once you click that link (or submit the token it contains), the change takes effect and the new address becomes active on your account.
The verification link sent to your new email address expires after **24 hours**. If it expires before you confirm it, restart the process by calling `POST /users/me/email` again.
## Email Change Flow
Call `POST /users/me/email` with your desired new email and your current password. The API verifies your password, checks that the new address is not already in use, and dispatches a verification email.
**`POST /users/me/email`**
Before sending this request, call `GET /auth/csrf-token` and include the returned token in the `x-csrf-token` header.
**Request Body**
The email address you want to switch to. Must be a valid email format and must not already be registered to another account.
Your current account password, used to re-authenticate the request.
```bash cURL theme={null}
# Step 1a — get CSRF token
CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
--cookie "session=" | jq -r '.data.csrf_token')
# Step 1b — request email change
curl -X POST https://api.example.com/api/v1/users/me/email \
--cookie "session=" \
-H "x-csrf-token: $CSRF" \
-H "Content-Type: application/json" \
-d '{
"new_email": "new@example.com",
"password": "S3cure!Pass"
}'
```
```javascript JavaScript theme={null}
// Step 1a — get CSRF token
const { data: csrfData } = await fetch(
"https://api.example.com/api/v1/auth/csrf-token",
{ credentials: "include" }
).then((r) => r.json());
// Step 1b — request email change
const response = await fetch(
"https://api.example.com/api/v1/users/me/email",
{
method: "POST",
credentials: "include",
headers: {
"Content-Type": "application/json",
"x-csrf-token": csrfData.csrf_token,
},
body: JSON.stringify({
new_email: "new@example.com",
password: "S3cure!Pass",
}),
}
);
// 202 Accepted — verification email queued
```
```python Python theme={null}
import requests
s = requests.Session()
s.cookies.set("session", "")
csrf = s.get(
"https://api.example.com/api/v1/auth/csrf-token"
).json()["data"]["csrf_token"]
resp = s.post(
"https://api.example.com/api/v1/users/me/email",
headers={"x-csrf-token": csrf},
json={"new_email": "new@example.com", "password": "S3cure!Pass"},
)
# 202 Accepted
```
**Response — 202 Accepted**
No response body is returned. A verification email has been queued to the new address.
**Error Responses**
| Status | Meaning |
| ------ | --------------------------------------------------------------- |
| `400` | Missing or invalid `new_email` or `password` field. |
| `401` | Wrong password or missing session cookie. |
| `409` | The new email address is already registered to another account. |
| `429` | Rate limit exceeded — check the `Retry-After` header. |
Open the verification email that arrives at your new address and extract the token from the link, or copy it directly. Then call `POST /users/me/email/verify` with that token while still authenticated.
**`POST /users/me/email/verify`**
You must still be authenticated with the same session that initiated the change. Obtain a fresh CSRF token before this call.
**Request Body**
The opaque verification token from the email link. Single-use and expires after 24 hours.
```bash cURL theme={null}
# Step 2a — get CSRF token
CSRF=$(curl -s -X GET https://api.example.com/api/v1/auth/csrf-token \
--cookie "session=" | jq -r '.data.csrf_token')
# Step 2b — verify the new email
curl -X POST https://api.example.com/api/v1/users/me/email/verify \
--cookie "session=" \
-H "x-csrf-token: $CSRF" \
-H "Content-Type: application/json" \
-d '{"token": "vrf_abc123"}'
```
```javascript JavaScript theme={null}
const { data: csrfData } = await fetch(
"https://api.example.com/api/v1/auth/csrf-token",
{ credentials: "include" }
).then((r) => r.json());
const response = await fetch(
"https://api.example.com/api/v1/users/me/email/verify",
{
method: "POST",
credentials: "include",
headers: {
"Content-Type": "application/json",
"x-csrf-token": csrfData.csrf_token,
},
body: JSON.stringify({ token: "vrf_abc123" }),
}
);
const result = await response.json();
```
```python Python theme={null}
csrf = s.get(
"https://api.example.com/api/v1/auth/csrf-token"
).json()["data"]["csrf_token"]
resp = s.post(
"https://api.example.com/api/v1/users/me/email/verify",
headers={"x-csrf-token": csrf},
json={"token": "vrf_abc123"},
)
print(resp.json())
```
**Response — 200 OK**
```json theme={null}
{
"success": true,
"data": {}
}
```
Your account email address is now updated to the new address. Future logins must use the new email.
**Error Responses**
| Status | Meaning |
| ------ | ---------------------------------------------------------- |
| `400` | `token` field is missing or malformed. |
| `401` | Session is missing or expired. |
| `404` | Token not found — it may have already been used. |
| `410` | Token has expired (older than 24 hours). Restart the flow. |