# Email change · Customer API

> Customer API reference for email change: GET /email-change, POST /email-change, POST /email-change/verify.

> Markdown version of https://kanorio.com/en/developers/customer-api/email-change. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp

Base URL: `https://{site}/api/v1/customer` · [Errors](https://kanorio.com/en/developers/basics/errors) · [Pagination](https://kanorio.com/en/developers/basics/pagination)

### Pending email change

`GET /email-change`

- Stability: beta

The new address a verification code was sent to, if a change is in progress.

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `pending` | object \| null | yes | — |
| `pending.email` | string | yes | The new address the code was sent to. |
| `pending.expiresAt` | string | yes | — |

```bash
curl -X GET "https://{site}/api/v1/customer/email-change" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN"
```

### Start changing the account email

`POST /email-change`

- Stability: beta

Sends a 6-digit verification code to the new address. The customer stays signed in. Fails with EMAIL_IN_USE when another customer of the site already uses the address (accounts are not merged). Limited to 5 requests per hour per customer; a new request replaces the previous code.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes | The new address; the code is sent there. |
| `locale` | string | no | Locale for the verification email; defaults to the customer's locale. |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `pending` | object \| null | yes | — |
| `pending.email` | string | yes | The new address the code was sent to. |
| `pending.expiresAt` | string | yes | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `INVALID_EMAIL` | 400 | — |
| `SAME_EMAIL` | 400 | — |
| `EMAIL_IN_USE` | 409 | — |
| `RATE_LIMITED` | 429 | — |
| `SERVICE_UNAVAILABLE` | 503 | — |
| `SEND_FAILED` | 502 | — |
| `SHARED_SENDER_PAUSED` | 503 | — |

```bash
curl -X POST "https://{site}/api/v1/customer/email-change" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Confirm the new email with the code

`POST /email-change/verify`

- Stability: beta

Replaces the account email and its sign-in identity. Existing sessions stay valid. Five wrong attempts invalidate the code.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | — |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `INVALID_CODE` | 400 | — |
| `CODE_EXPIRED` | 410 | — |
| `TOO_MANY_ATTEMPTS` | 429 | — |
| `EMAIL_IN_USE` | 409 | — |

```bash
curl -X POST "https://{site}/api/v1/customer/email-change/verify" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```
