# identities.delete

Delete a mailbox.

Soft-deletes a mailbox with a 7-day retention window for recovery. Pass purge=true to immediately queue the mailbox for permanent deletion.

```ts
openemail.identities.delete(
  identityId: string,
  options?: IdentitiesDeleteOptions,
): ApiPromise<MailboxDeleteResult>
```

It calls `DELETE /identities/{identityId}`: [Delete a mailbox](/docs/api/mailboxes/delete_IdentityDelete) in the API reference.

## Example

```ts
const mailboxDeleteResult = await openemail.identities.delete(identityId)
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `identityId` | `string` | Identity ULID identifier. The path's `{identityId}`. |

## Options

The last argument, `options`, a `IdentitiesDeleteOptions`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `purge` | `boolean` | query `purge` | Set to 'true' to permanently purge the mailbox immediately without a 7-day retention window. A system key's, or redundant on a mailbox created ephemeral (#483); from an account key on any other mailbox it is refused 403 system_credentials_required — the window is the undo a leaked key must not be able to waive |

Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`MailboxDeleteResult`](/docs/sdks/typescript/types/mailbox-delete-result). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `403` | system_credentials_required (purge=true from an account key on a mailbox not created ephemeral, #483) \| account_credentials_required — a DOMAIN-SCOPED api key named a mailbox that is also routed on a domain outside its scope. Restore rebinds the mailbox's primary address, so deleting one primaried elsewhere could not be undone without writing a route on a domain this key does not hold; the account's own key may delete it |
| `404` | Mailbox not found or not accessible to this principal |
| `409` | mailbox_is_group_persona — this identity is a group's persona (its archive and sending identity); delete the group route instead, which tears the persona down with it |
| `503` | temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

It names these types of the API, each on a page of its own: [`MailboxDeleteResult`](/docs/sdks/typescript/types/mailbox-delete-result).
