# Change your email address

URL: https://heaven.dev/docs/reference/account/email
Updated: 2026-11-21

Change your sign-in and contact email address. Request verification codes for both addresses, then submit both codes to complete the change. Heaven claims invitations for the new address and updates receipt delivery if it used the old address.

`POST /v1/account/modify`

## Parameters

- `email` (string, required): Your new sign-in email address, such as ada@example.com.
- `code` (string): Verification code sent to your new email address. Treated as a secret and never included in errors.
- `old_code` (string): Verification code sent to your current email address. Treated as a secret and never included in errors.

## Returns

- `data` (object, always present): Confirmation code recipients and deadline, or the verified address after confirmation.
  - `alternative-1` (object): Your verified email address after the change.
    - `email` (string, always present): Address now associated with your account.
  - `alternative-2` (object): Confirmation recipients and deadline for an email address change.
    - `code_expires_at` (string (date-time), always present): Deadline for submitting the confirmation codes.
    - `code_sent_to` (string, always present): New email address receiving a confirmation code.
    - `old_code_sent_to` (string, always present): Current address receiving the second code. Empty when no current address requires confirmation.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `payment_required` | 402 | Payment or credit is required. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- CLI: `heaven login` with `HEAVEN_API_KEY` unset. MCP: Heaven sign-in. cURL: `HEAVEN_SIGN_IN_KEY` from approved device sign-in (`POST /v1/auth/create`).
- A key limited to a command list cannot run this command.
- **Send codes:** Send verification codes to both the current and new email addresses.
- **Change:** Change your email address after verifying both codes. Required: `code`, `old_code`.

## Examples

```sh tab="heaven CLI"
heaven account email EMAIL
  [--code CODE]
  [--old-code OLD-CODE]
```

```sh tab="SSH"
ssh cli@heaven.dev account email EMAIL
  [--code CODE]
  [--old-code OLD-CODE]
```

```sh tab="cURL"
curl https://heaven.dev/v1/account/modify \
  -H "Authorization: Bearer $HEAVEN_SIGN_IN_KEY" \
  --json '{"action": "email", "email": "ada@example.com"}'
```

```json tab="MCP"
{ "tool": "account_email",
  "arguments": { "email": "ada@example.com" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "code_expires_at": "2026-11-16T12:15:00Z",
    "code_sent_to": "ada@example.com",
    "old_code_sent_to": "you@example.com"
  }
}
```
