---
title: "Remove email"
method: DELETE
path: "/api/v1/me/emails/{id}"
tags: ["Emails"]
---

# Remove email

`DELETE /api/v1/me/emails/{id}`

## Request

- Base URL: `https://api.proof.holdings`
- URL: `https://api.proof.holdings/api/v1/me/emails/{id}`
- Auth: API key in cookie `auth_token`

Remove an email address from the account (h-implement-proper-deletion, PE-2). Refused with 409 while it is the identifier this session signed in with (`login_identifier`), the last sign-in method across phones and emails (`last_login_method`). Otherwise, after a single-use `email_remove` step-up grant bound to this id is consumed (`403 2fa_required` without one; `reason: target_mismatch` when the grant names other ids): every proof of an email address is revoked, approval consents naming it are revoked, approval setups left without an approver are marked and their pending requests declined, the primary flag moves deterministically to the oldest remaining email and Lookalike Watch alerts are re-pointed to it (or paused when none is left), the row is hard-deleted, the other sessions are signed out, and a notice goes to the contacts captured before the delete. The response names the new primary. Cannot be undone. `GET /me/emails/{id}/removal-preview` shows the same counts beforehand.

## Path parameters

- `id` string, required: MongoDB ObjectId

## Response `200`

Email removed — the cascade, line by line

- IdentifierRemovedResponse: The cascade a removal performed, line by line — the same lines the notice carries.
  - `success` true, required
  - `type` 'phone' | 'email', required
  - `removed_id` string, required
  - `identifier` string, required: Masked.
  - `proofs_revoked` integer, required
  - `authorizations_revoked` integer, required
  - `hitl_configs_without_approver` object[], required
    - `id` string, required
    - `name` string, nullable, required
    - `confirmations_denied` integer, required
  - `circles_repointed` integer, required: Phones only: circles that now reach the owner at `new_primary`; 0 for an email.
  - `new_primary` object, nullable, required: The row that becomes (or became) primary when the removed one was; null otherwise.
    - `id` string, required
    - `identifier` string, required: Masked.
  - `lookalike_watch` 'repointed' | 'canceled' | 'unchanged', required
  - `sessions_invalidated` integer, required: Other listed devices signed out, idle ones included; the calling session stays. A device missing from the list — signed in before the list held idle devices, or one whose listing could not be recorded — is not counted, so read `sessions_signed_out` for whether every other device was signed out.
  - `sessions_signed_out` boolean, required: Every other device was signed out, idle ones included; the calling session stays. False when that could not be done — the removal itself still happened.
  - `notice` object[], required
    - `kind` 'email' | 'telegram' | 'whatsapp', required
    - `address` string, required: Masked.
    - `outcome` string, required: `sent`, `skipped:<why>` or `failed:<why>`. A notice is a courtesy after an act that already committed; a failed one never fails the request.

## Other responses

- `403`: `2fa_required` — a single-use step-up grant bound to this id is required (`reason: target_mismatch` when the grant names other ids); nothing was changed
- `404`: Email not found
- `409`: `login_identifier`, `last_login_method` or `circles_need_phone` — a guard refused the removal; nothing was changed

---

[API](https://skmtc.dev/proof/apis/proof-holdings-api.md) · [All operations](https://skmtc.dev/proof/apis/proof-holdings-api/llms.txt) · [OpenAPI document](https://skmtc.dev/proof/apis/proof-holdings-api/revisions/6b8d61ee354f?raw)