Skip to content

Change your email address

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.

Parameters

#
emailstringRequired
Your new sign-in email address, such as ada@example.com.
codestring
Verification code sent to your new email address. Treated as a secret and never included in errors.
old_codestring
Verification code sent to your current email address. Treated as a secret and never included in errors.

Returns

#
dataobjectAlways present
Confirmation code recipients and deadline, or the verified address after confirmation.
Show 2 attributesHide attributes
alternative-1object
Your verified email address after the change.
Show 1 attributeHide attributes
emailstringAlways present
Address now associated with your account.
alternative-2object
Confirmation recipients and deadline for an email address change.
Show 3 attributesHide attributes
code_expires_atstring (date-time)Always present
Deadline for submitting the confirmation codes.
code_sent_tostringAlways present
New email address receiving a confirmation code.
old_code_sent_tostringAlways present
Current address receiving the second code. Empty when no current address requires confirmation.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The 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.